orcastrator 0.1.1 → 0.2.0

package/README.md

@@ -1,86 +1,200 @@
 # orca
 
-Orca is a TypeScript CLI harness for coordinated agent planning and execution. It takes a goal or spec file, uses Claude to decompose it into a task graph, runs a pre-execution review pass with Codex, then executes each task via a persistent Codex thread — keeping full context across the entire run.
-
-**Pipeline:** Claude plans → Codex reviews task graph → Codex executes (persistent thread) → Codex post-run review
+Coordinated agent run harness. Breaks down a goal into a task graph, then executes it end-to-end via a persistent [Codex](https://github.com/ratley/codex-client) session with full context across tasks.
 
 ## Install
 
 ```bash
-bun install
+npm install -g orcastrator
 ```
 
-## Usage
+## Run A Goal
 
-### Inline goal (no file needed)
+Start with a plain-language goal:
 
 ```bash
-orca -p "add a settings screen to the iOS app"
-orca --prompt "refactor the auth module to use JWTs"
-orca --task "write unit tests for the payments service"
+orca "add auth to the app"
 ```
 
-### Spec file
+Orca will create a run, plan tasks, execute them, and persist run state.
+
+## Spec And Plan Files
+
+Use a spec/plan markdown file when you already have a written breakdown:
 
 ```bash
-orca run --spec ./specs/myfeature.md
+orca --spec ./specs/feature.md
+orca --plan ./specs/feature.md
 ```
 
-`run` is optional — the above is equivalent to:
+If you only want planning (no execution):
 
 ```bash
-orca --spec ./specs/myfeature.md
+orca plan --spec ./specs/feature.md
 ```
 
-### Other commands
+## Run Management
 
 ```bash
-orca plan --spec ./specs/myfeature.md   # plan only, no execution
-orca status --run <run-id>              # show status for a specific run
-orca status                             # list all runs with status
-orca list                               # list all runs
-orca resume --run <run-id>             # resume an incomplete run
-orca cancel --run <run-id>             # cancel an active run
-orca pr-finalize --run <run-id>        # finalize a prepared pull request
+orca status
+orca status --last
+orca status --run <run-id>
+
+orca list
+
+orca resume --last
+orca resume --run <run-id>
+
+orca cancel --last
+orca cancel --run <run-id>
+
+orca answer <run-id> "yes, use migration A"
 ```
 
-### Hooks
+## PR Workflow
 
 ```bash
-orca -p "build X" \
-  --on-task-complete "echo task done: $ORCA_TASK_NAME" \
-  --on-complete "open -a Terminal" \
-  --on-error "say orca failed"
+orca pr
+orca pr draft --run <run-id>
+orca pr create --run <run-id>
+orca pr publish --run <run-id>
+orca pr status --run <run-id>
+
+orca pr-finalize --config ./orca.config.js
 ```
 
-Available hooks: `--on-milestone`, `--on-task-complete`, `--on-task-fail`, `--on-complete`, `--on-error`
+## Config
 
-## Run output
+Orca auto-discovers config in this order:
 
-Run state is written to:
+1. `~/.orca/config.js`
+2. `./orca.config.js` or `./orca.config.ts`
+3. `--config <path>` (if passed)
 
-```text
-~/.orca/runs/<run-id>/status.json
+Later entries override earlier ones.
+
+```js
+// orca.config.js
+export default {
+  runsDir: "./.orca/runs",
+  sessionLogs: "./session-logs",
+  hookCommands: {
+    onTaskComplete: "echo task done: $ORCA_TASK_NAME",
+    onComplete: "echo run complete",
+    onError: "echo run failed"
+  }
+};
 ```
 
-Run IDs follow the format:
+## Reference
 
-```text
-<spec-slug>-<timestamp-ms>-<4char-hex>
-```
+### Flags
 
-## Dev
+Global:
 
-```bash
-bun test              # run tests
-bun run src/cli/index.ts -p "your goal here"   # run without building
-```
+- `-h, --help`
+- `-V, --version`
+
+`orca` / `orca run`:
+
+- positional: `[goal]`
+- also works: `--task <text>`, `-p, --prompt <text>`
+- `--spec <path>`
+- `--plan <path>`
+- `--config <path>`
+- `--on-milestone <cmd>`
+- `--on-task-complete <cmd>`
+- `--on-task-fail <cmd>`
+- `--on-complete <cmd>`
+- `--on-error <cmd>`
+
+`orca plan`:
+
+- `--spec <path>`
+- `--config <path>`
+- `--on-milestone <cmd>`
+- `--on-error <cmd>`
+
+`orca status`:
+
+- `--run <run-id>`
+- `--last`
+- `--config <path>`
+
+`orca resume`:
+
+- `--run <run-id>`
+- `--last`
+- `--config <path>`
+
+`orca cancel`:
+
+- `--run <run-id>`
+- `--last`
+- `--config <path>`
+
+`orca answer`:
 
-## Architecture
+- positional: `[run-id] [answer]`
+- `--run <id>`
 
-| Step | Model | What |
-|------|-------|------|
-| Planning | Claude | Spec → task graph (dependency-aware DAG) |
-| Phase 4 review | Codex | Reviews task graph before execution; aborts on hard blockers |
-| Execution | Codex | Persistent thread runs each task (full context across tasks) |
-| Post-run review | Codex | Reviews all changes after execution completes |
+`orca list`:
+
+- `--config <path>`
+
+`orca pr draft|create|publish|status`:
+
+- `--run <run-id>`
+- `--last`
+- `--config <path>`
+
+`orca pr-finalize`:
+
+- `--config <path>`
+
+`orca setup`:
+
+- `--anthropic-key <key>`
+- `--openai-key <key>`
+- `--check`
+- `--global`
+- `--project`
+
+### Hooks
+
+Hook names:
+
+- `onMilestone`
+- `onTaskComplete`
+- `onTaskFail`
+- `onComplete`
+- `onError`
+
+Run hooks from CLI with `--on-...` flags or from config via `hookCommands` / `hooks`.
+
+### Run ID Format
+
+Run IDs are generated as:
+
+- `<slug>-<unix-ms>-<hex4>`
+- Example: `feature-auth-1766228123456-1a2b`
+
+### Config File Locations
+
+- Global: `~/.orca/config.js`
+- Project: `./orca.config.js` or `./orca.config.ts`
+- Explicit: `--config <path>`
+
+### Run State Locations
+
+- Run status: `<runsDir>/<run-id>/status.json`
+- Answer payloads: `<runsDir>/<run-id>/answer.txt`
+- `runsDir` defaults to `~/.orca/runs` unless overridden by `ORCA_RUNS_DIR`.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run src/cli/index.ts "your goal here"
+```

package/dist/cli/commands/answer.js

@@ -0,0 +1,61 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import { input } from "@inquirer/prompts";
+import { RunStore } from "../../state/store.js";
+import { selectRun } from "../../utils/select-run.js";
+function createStore() {
+    const runsDir = process.env.ORCA_RUNS_DIR;
+    return runsDir ? new RunStore(runsDir) : new RunStore();
+}
+function resolveRunId(positionalRunId, optionRunId) {
+    if (positionalRunId && optionRunId) {
+        throw new Error("positional run-id and --run are mutually exclusive");
+    }
+    return positionalRunId ?? optionRunId;
+}
+async function resolveAnswer(answerArg) {
+    if (answerArg) {
+        return answerArg;
+    }
+    if (!process.stdout.isTTY) {
+        throw new Error("no answer provided");
+    }
+    const value = await input({ message: "Answer:" });
+    if (!value) {
+        throw new Error("no answer provided");
+    }
+    return value;
+}
+export async function answerCommandHandler(positionalRunId, answerArg, options) {
+    const store = createStore();
+    let runId = resolveRunId(positionalRunId, options.run);
+    if (!runId) {
+        if (!process.stdout.isTTY) {
+            throw new Error("no run id provided");
+        }
+        runId = await selectRun(store) ?? undefined;
+        if (!runId) {
+            throw new Error("no run id provided");
+        }
+    }
+    const run = await store.getRun(runId);
+    if (!run) {
+        throw new Error(`Run not found: ${runId}`);
+    }
+    if (run.overallStatus !== "waiting_for_answer") {
+        throw new Error(`Run ${runId} is not waiting for an answer.`);
+    }
+    const answer = await resolveAnswer(answerArg);
+    const answerPath = path.join(store.getRunDir(runId), "answer.txt");
+    await fs.mkdir(path.dirname(answerPath), { recursive: true });
+    await fs.writeFile(answerPath, `${answer}\n`, "utf8");
+    await store.updateRun(runId, { overallStatus: "running" });
+    console.log(`Answer submitted. Run ${runId} will resume shortly.`);
+}
+export function registerAnswerCommand(program) {
+    program
+        .command("answer [run-id] [answer]")
+        .description("Submit an answer for a run waiting for input")
+        .option("--run <id>", "Run ID waiting for answer")
+        .action(async (runId, answer, options) => answerCommandHandler(runId, answer, options));
+}

package/dist/cli/commands/cancel.js

@@ -1,4 +1,5 @@
 import { RunStore } from "../../state/store.js";
+import { getLastRun } from "../../utils/last-run.js";
 function createStore() {
     const runsDir = process.env.ORCA_RUNS_DIR;
     return runsDir ? new RunStore(runsDir) : new RunStore();
@@ -14,6 +15,15 @@ function getActiveRuns(runs) {
 }
 export async function cancelCommandHandler(options) {
     const store = createStore();
+    if (options.last) {
+        const lastRun = await getLastRun(store);
+        if (!lastRun) {
+            console.error("No runs found.");
+            process.exitCode = 1;
+            return;
+        }
+        options.run = lastRun.runId;
+    }
     const knownRuns = await store.listRuns();
     if (!options.run) {
         console.error(`Missing required --run <run-id>\nActive runs: ${formatRunIds(getActiveRuns(knownRuns))}`);
@@ -55,6 +65,7 @@ export function registerCancelCommand(program) {
         .command("cancel")
         .description("Cancel an active run")
         .option("--run <run-id>", "Run ID to cancel")
+        .option("--last", "Use the most recent run")
         .option("--config <path>", "Path to orca config file")
         .action(async (options) => cancelCommandHandler(options));
 }

package/dist/cli/commands/help.js

@@ -0,0 +1,87 @@
+import chalk from "chalk";
+const HELP_COLUMN_WIDTH = 40;
+function formatHelpLine(command, description) {
+    return `  ${chalk.cyan(command.padEnd(HELP_COLUMN_WIDTH, " "))}${chalk.dim(description)}`;
+}
+function printSection(title, entries) {
+    console.log(chalk.bold(title));
+    for (const entry of entries) {
+        console.log(formatHelpLine(entry.command, entry.description));
+    }
+    console.log("");
+}
+function printStyledHelpPage() {
+    console.log("orca — coordinated agent run harness");
+    console.log("");
+    printSection("RUNNING", [
+        { command: 'orca "add auth to the app"', description: "run with inline goal" },
+        { command: "orca --plan ./specs/feature.md", description: "run from plan file" },
+        { command: "orca plan --spec ./specs/feature.md", description: "plan only, no execution" }
+    ]);
+    printSection("RUN MANAGEMENT", [
+        { command: "orca status", description: "list all runs" },
+        { command: "orca status --last", description: "show most recent run" },
+        { command: "orca status --run <id>", description: "show run details" },
+        { command: "orca resume --last", description: "resume most recent run" },
+        { command: "orca resume --run <id>", description: "resume incomplete run" },
+        { command: "orca cancel --run <id>", description: "cancel active run" }
+    ]);
+    printSection("PULL REQUESTS", [
+        { command: "orca pr", description: "interactive — pick run + action" },
+        { command: "orca pr draft --run <id>", description: "create draft PR" },
+        { command: "orca pr create --run <id>", description: "create ready-for-review PR" },
+        { command: "orca pr publish --run <id>", description: "publish draft → ready for review" },
+        { command: "orca pr status --run <id>", description: "check PR state and CI" }
+    ]);
+    printSection("SETUP", [
+        { command: "orca setup", description: "first-time setup and environment checks" }
+    ]);
+    printSection("FLAGS", [
+        { command: "-p, --prompt <text>", description: "inline task goal (alias: --task)" },
+        { command: "--plan, --spec <path>", description: "path to spec or plan file" },
+        { command: "--run <id>", description: "specify run by ID" },
+        { command: "--last", description: "use the most recent run" },
+        {
+            command: "--config <path>",
+            description: "explicit config file (auto-discovered by default)"
+        },
+        { command: "--full-auto", description: "skip all questions, proceed autonomously" },
+        { command: "--on-complete <cmd>", description: "shell hook on run complete" },
+        { command: "--on-error <cmd>", description: "shell hook on run error" },
+        { command: "-h, --help", description: "show help for any command" },
+        { command: "-V, --version", description: "show version" }
+    ]);
+}
+function findCommand(program, pathText) {
+    const segments = pathText
+        .split(" ")
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+    let current = program;
+    for (const segment of segments) {
+        current = current.commands.find((command) => command.name() === segment);
+        if (!current) {
+            return undefined;
+        }
+    }
+    return current;
+}
+export function registerHelpCommand(program) {
+    program.addHelpCommand(false);
+    program
+        .command("help [command]")
+        .description("display help for command")
+        .action((commandPath) => {
+        if (!commandPath) {
+            printStyledHelpPage();
+            return;
+        }
+        const target = findCommand(program, commandPath);
+        if (!target) {
+            console.error(`error: unknown command '${commandPath}'`);
+            process.exitCode = 1;
+            return;
+        }
+        target.outputHelp();
+    });
+}

package/dist/cli/commands/pr/create.js

@@ -0,0 +1,57 @@
+import { checkGhCli, runGh } from "../../../utils/gh.js";
+import { buildPrBody, buildPrTitle, createStore, loadRunOrExit, printGhMissingAndExit, resolveRunIdOrExit } from "./shared.js";
+function parsePrUrl(stdout) {
+    const lines = stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    return lines.at(-1) ?? null;
+}
+export async function prCreateCommandHandler(options) {
+    const runId = await resolveRunIdOrExit(options, "create");
+    if (!runId) {
+        return;
+    }
+    const run = await loadRunOrExit(options);
+    if (!run) {
+        return;
+    }
+    if (!(await checkGhCli())) {
+        printGhMissingAndExit();
+        return;
+    }
+    const title = buildPrTitle(run);
+    const body = buildPrBody(run);
+    const result = await runGh(["pr", "create", "--title", title, "--body", body]);
+    if (result.exitCode !== 0) {
+        console.error(result.stderr || result.stdout || "Failed to create PR.");
+        process.exitCode = 1;
+        return;
+    }
+    const url = parsePrUrl(result.stdout);
+    if (!url) {
+        console.error("PR created, but URL could not be determined.");
+        process.exitCode = 1;
+        return;
+    }
+    const store = createStore();
+    await store.updateRun(runId, {
+        pr: {
+            ...run.pr,
+            url,
+            draftTitle: title,
+            draftBody: body,
+            readyForFinalize: true
+        }
+    });
+    console.log(url);
+}
+export function registerPrCreateCommand(program) {
+    program
+        .command("create")
+        .description("Create a pull request for a run")
+        .option("--run <run-id>", "Run ID to create PR for")
+        .option("--last", "Use the most recent run")
+        .option("--config <path>", "Path to orca config file")
+        .action(async (options) => prCreateCommandHandler(options));
+}

package/dist/cli/commands/pr/draft.js

@@ -0,0 +1,57 @@
+import { runGh, checkGhCli } from "../../../utils/gh.js";
+import { buildPrBody, buildPrTitle, createStore, loadRunOrExit, printGhMissingAndExit, resolveRunIdOrExit } from "./shared.js";
+function parsePrUrl(stdout) {
+    const lines = stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    return lines.at(-1) ?? null;
+}
+export async function prDraftCommandHandler(options) {
+    const runId = await resolveRunIdOrExit(options, "draft");
+    if (!runId) {
+        return;
+    }
+    const run = await loadRunOrExit(options);
+    if (!run) {
+        return;
+    }
+    if (!(await checkGhCli())) {
+        printGhMissingAndExit();
+        return;
+    }
+    const title = buildPrTitle(run);
+    const body = buildPrBody(run);
+    const result = await runGh(["pr", "create", "--draft", "--title", title, "--body", body]);
+    if (result.exitCode !== 0) {
+        console.error(result.stderr || result.stdout || "Failed to create draft PR.");
+        process.exitCode = 1;
+        return;
+    }
+    const url = parsePrUrl(result.stdout);
+    if (!url) {
+        console.error("Draft PR created, but URL could not be determined.");
+        process.exitCode = 1;
+        return;
+    }
+    const store = createStore();
+    await store.updateRun(runId, {
+        pr: {
+            ...run.pr,
+            url,
+            draftTitle: title,
+            draftBody: body,
+            readyForFinalize: false
+        }
+    });
+    console.log(url);
+}
+export function registerPrDraftCommand(program) {
+    program
+        .command("draft")
+        .description("Create a draft pull request for a run")
+        .option("--run <run-id>", "Run ID to create draft PR for")
+        .option("--last", "Use the most recent run")
+        .option("--config <path>", "Path to orca config file")
+        .action(async (options) => prDraftCommandHandler(options));
+}

package/dist/cli/commands/pr/index.js

@@ -0,0 +1,66 @@
+import { select } from "@inquirer/prompts";
+import { prCreateCommandHandler, registerPrCreateCommand } from "./create.js";
+import { prDraftCommandHandler, registerPrDraftCommand } from "./draft.js";
+import { prPublishCommandHandler, registerPrPublishCommand } from "./publish.js";
+import { createStore } from "./shared.js";
+import { prStatusCommandHandler, registerPrStatusCommand } from "./status.js";
+import { selectRun } from "../../../utils/select-run.js";
+export function registerPrCommand(program) {
+    const prCommand = program
+        .command("pr")
+        .description("Pull request workflow commands");
+    registerPrDraftCommand(prCommand);
+    registerPrCreateCommand(prCommand);
+    registerPrPublishCommand(prCommand);
+    registerPrStatusCommand(prCommand);
+    prCommand
+        .command("finalize")
+        .description("Deprecated: use `orca pr publish`")
+        .requiredOption("--run <run-id>", "")
+        .action(async (options) => prPublishCommandHandler(options));
+    prCommand.action(async () => {
+        if (!process.stdout.isTTY) {
+            console.error("Usage: orca pr <draft|create|publish|status> --run <id>");
+            process.exitCode = 1;
+            return;
+        }
+        const store = createStore();
+        const runId = await selectRun(store);
+        if (!runId) {
+            return;
+        }
+        const run = await store.getRun(runId);
+        if (!run) {
+            return;
+        }
+        if (run.pr?.url) {
+            const state = run.pr.finalizedAt ? "published (ready for review)" : "draft";
+            console.log(`PR: ${run.pr.url} [${state}]`);
+        }
+        else {
+            console.log("No PR for this run yet.");
+        }
+        const action = await select({
+            message: "What do you want to do?",
+            choices: [
+                { name: "Create draft PR", value: "draft" },
+                { name: "Create PR (ready for review)", value: "create" },
+                { name: "Publish draft → ready for review", value: "publish" },
+                { name: "View PR status & CI checks", value: "status" }
+            ]
+        });
+        const options = { run: runId };
+        if (action === "draft") {
+            await prDraftCommandHandler(options);
+        }
+        else if (action === "create") {
+            await prCreateCommandHandler(options);
+        }
+        else if (action === "publish") {
+            await prPublishCommandHandler(options);
+        }
+        else if (action === "status") {
+            await prStatusCommandHandler(options);
+        }
+    });
+}

package/dist/cli/commands/pr/publish.js

@@ -0,0 +1,45 @@
+import { checkGhCli, runGh } from "../../../utils/gh.js";
+import { createStore, loadRunOrExit, printGhMissingAndExit, resolveRunIdOrExit } from "./shared.js";
+export async function prPublishCommandHandler(options) {
+    const runId = await resolveRunIdOrExit(options, "publish");
+    if (!runId) {
+        return;
+    }
+    const run = await loadRunOrExit(options);
+    if (!run) {
+        return;
+    }
+    if (!(await checkGhCli())) {
+        printGhMissingAndExit();
+        return;
+    }
+    if (!run.pr?.url) {
+        console.error("No PR found for this run. Use `orca pr draft` or `orca pr create` first.");
+        process.exitCode = 1;
+        return;
+    }
+    const result = await runGh(["pr", "ready", run.pr.url]);
+    if (result.exitCode !== 0) {
+        console.error(result.stderr || result.stdout || "Failed to mark PR ready for review.");
+        process.exitCode = 1;
+        return;
+    }
+    const store = createStore();
+    await store.updateRun(runId, {
+        pr: {
+            ...run.pr,
+            readyForFinalize: true,
+            finalizedAt: new Date().toISOString()
+        }
+    });
+    console.log(`PR marked ready for review: ${run.pr.url}`);
+}
+export function registerPrPublishCommand(program) {
+    program
+        .command("publish")
+        .description("Publish a draft PR (mark ready for review)")
+        .option("--run <run-id>", "Run ID to publish PR for")
+        .option("--last", "Use the most recent run")
+        .option("--config <path>", "Path to orca config file")
+        .action(async (options) => prPublishCommandHandler(options));
+}

package/dist/cli/commands/pr/shared.js

@@ -0,0 +1,79 @@
+import path from "node:path";
+import { RunStore } from "../../../state/store.js";
+import { getLastRun } from "../../../utils/last-run.js";
+import { selectRun } from "../../../utils/select-run.js";
+export function createStore() {
+    const runsDir = process.env.ORCA_RUNS_DIR;
+    return runsDir ? new RunStore(runsDir) : new RunStore();
+}
+export function buildPrTitle(run) {
+    const specBase = run.specPath ? path.basename(run.specPath) : "";
+    const derived = specBase.length > 0 ? specBase : run.runId;
+    return `Orca run: ${derived}`;
+}
+export function buildPrBody(run) {
+    const completedTasks = run.tasks.filter((task) => task.status === "done");
+    const lines = [
+        `Automated PR for run \`${run.runId}\`.`,
+        "",
+        `Spec: \`${run.specPath}\``,
+        "",
+        "Completed tasks:"
+    ];
+    if (completedTasks.length === 0) {
+        lines.push("- (none)");
+    }
+    else {
+        for (const task of completedTasks) {
+            lines.push(`- [x] ${task.name} (${task.id})`);
+        }
+    }
+    return lines.join("\n");
+}
+export async function loadRunOrExit(options) {
+    if (!options.run) {
+        console.error("Run ID is required.");
+        process.exitCode = 1;
+        return null;
+    }
+    const store = createStore();
+    const run = await store.getRun(options.run);
+    if (!run) {
+        console.error(`Run not found: ${options.run}`);
+        process.exitCode = 1;
+        return null;
+    }
+    return run;
+}
+export function printGhMissingAndExit() {
+    console.error("gh CLI not found. Run `orca setup` to install it.");
+    process.exitCode = 1;
+}
+export async function resolveRunIdOrExit(options, commandName) {
+    if (options.last) {
+        const store = createStore();
+        const lastRun = await getLastRun(store);
+        if (!lastRun) {
+            console.error("No runs found.");
+            process.exitCode = 1;
+            return null;
+        }
+        options.run = lastRun.runId;
+        return lastRun.runId;
+    }
+    if (options.run) {
+        return options.run;
+    }
+    if (!process.stdout.isTTY) {
+        console.error(`missing --run <run-id>. Usage: orca pr ${commandName} --run <id>`);
+        process.exitCode = 1;
+        return null;
+    }
+    const runId = await selectRun(createStore());
+    if (!runId) {
+        process.exitCode = 1;
+        return null;
+    }
+    options.run = runId;
+    return runId;
+}

package/dist/cli/commands/pr/status.js

@@ -0,0 +1,64 @@
+import { checkGhCli, runGh } from "../../../utils/gh.js";
+import { loadRunOrExit, printGhMissingAndExit, resolveRunIdOrExit } from "./shared.js";
+function stringifyCheckStatus(check) {
+    const primary = check.status ?? check.state ?? "UNKNOWN";
+    const conclusion = check.conclusion ? `/${check.conclusion}` : "";
+    return `${primary}${conclusion}`;
+}
+function checkName(check) {
+    return check.name ?? check.context ?? "unnamed-check";
+}
+export async function prStatusCommandHandler(options) {
+    if (!(await resolveRunIdOrExit(options, "status"))) {
+        return;
+    }
+    const run = await loadRunOrExit(options);
+    if (!run) {
+        return;
+    }
+    if (!(await checkGhCli())) {
+        printGhMissingAndExit();
+        return;
+    }
+    if (!run.pr?.url) {
+        console.error("No PR associated with this run.");
+        process.exitCode = 1;
+        return;
+    }
+    const result = await runGh(["pr", "view", run.pr.url, "--json", "state,statusCheckRollup,title,url"]);
+    if (result.exitCode !== 0) {
+        console.error(result.stderr || result.stdout || "Failed to load PR status.");
+        process.exitCode = 1;
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        console.error("Failed to parse PR status output.");
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Title: ${parsed.title ?? "-"}`);
+    console.log(`State: ${parsed.state ?? "-"}`);
+    console.log(`URL: ${parsed.url ?? run.pr.url}`);
+    console.log("Checks:");
+    const checks = parsed.statusCheckRollup ?? [];
+    if (checks.length === 0) {
+        console.log("- (none)");
+        return;
+    }
+    for (const check of checks) {
+        console.log(`- ${checkName(check)}: ${stringifyCheckStatus(check)}`);
+    }
+}
+export function registerPrStatusCommand(program) {
+    program
+        .command("status")
+        .description("Show pull request status for a run")
+        .option("--run <run-id>", "Run ID to inspect PR for")
+        .option("--last", "Use the most recent run")
+        .option("--config <path>", "Path to orca config file")
+        .action(async (options) => prStatusCommandHandler(options));
+}

package/dist/cli/commands/resume.js

@@ -1,5 +1,6 @@
 import { runTaskRunner } from "../../core/task-runner.js";
 import { RunStore } from "../../state/store.js";
+import { getLastRun } from "../../utils/last-run.js";
 function createStore() {
     const runsDir = process.env.ORCA_RUNS_DIR;
     return runsDir ? new RunStore(runsDir) : new RunStore();
@@ -15,6 +16,15 @@ function getActiveRuns(runs) {
 }
 export async function resumeCommandHandler(options) {
     const store = createStore();
+    if (options.last) {
+        const lastRun = await getLastRun(store);
+        if (!lastRun) {
+            console.error("No runs found.");
+            process.exitCode = 1;
+            return;
+        }
+        options.run = lastRun.runId;
+    }
     const knownRuns = await store.listRuns();
     if (!options.run) {
         console.error(`Missing required --run <run-id>\nActive runs: ${formatRunIds(getActiveRuns(knownRuns))}`);
@@ -62,6 +72,7 @@ export function registerResumeCommand(program) {
         .command("resume")
         .description("Resume an incomplete run")
         .option("--run <run-id>", "Run ID to resume")
+        .option("--last", "Use the most recent run")
         .option("--config <path>", "Path to orca config file")
         .action(async (options) => resumeCommandHandler(options));
 }

package/dist/cli/commands/run.js

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { createCodexSession } from "../../agents/codex/session.js";
-import { loadConfig } from "../../core/config-loader.js";
+import { resolveConfig } from "../../core/config-loader.js";
 import { runPlanner } from "../../core/planner.js";
 import { runTaskRunner } from "../../core/task-runner.js";
 import { createOpenclawHookHandler, detectOpenclawAvailability } from "../../hooks/adapters/openclaw.js";
@@ -49,23 +49,30 @@ function buildCliCommandHooks(options) {
     };
 }
 export async function runCommandHandler(options) {
-    const inlineTask = options.task ?? options.prompt;
-    if (!options.spec && !inlineTask) {
+    const inlineTask = options.task ?? options.prompt ?? options.goal;
+    const inputSpecPath = options.spec ?? options.plan;
+    if (options.goal !== undefined && (options.task || options.prompt)) {
+        throw new Error("positional goal and --task/--prompt are mutually exclusive");
+    }
+    if (options.goal !== undefined && inputSpecPath) {
+        throw new Error("positional goal and --spec/--plan are mutually exclusive");
+    }
+    if (!inputSpecPath && !inlineTask) {
         throw new Error("One of --spec, --task, or --prompt (-p) must be provided.");
     }
-    if (options.spec && inlineTask) {
+    if (inputSpecPath && inlineTask) {
         throw new Error("--spec is mutually exclusive with --task / --prompt.");
     }
     const usesInlineTask = Boolean(inlineTask);
     const specPath = usesInlineTask
         ? path.join(os.tmpdir(), `orca-task-${Date.now()}-${randomUUID()}.md`)
-        : path.resolve(options.spec ?? "");
+        : path.resolve(inputSpecPath ?? "");
     if (usesInlineTask) {
         await writeFile(specPath, `${inlineTask}\n`, "utf8");
     }
     try {
         await access(specPath, fsConstants.R_OK);
-        const orcaConfig = await loadConfig(options.config);
+        const orcaConfig = await resolveConfig(options.config);
         const runId = generateRunId(specPath);
         console.log(`Run ID: ${runId}`);
         const store = createStore();
@@ -175,9 +182,10 @@ export async function runCommandHandler(options) {
 }
 export function registerRunCommand(program) {
     program
-        .command("run", { isDefault: true })
+        .command("run [goal]", { isDefault: true })
         .description("Run pre-planning and execution")
         .option("--spec <path>", "Path to spec markdown file")
+        .option("--plan <path>", "Alias for --spec — path to a plan/spec file")
         .option("--task <text>", "Inline task text (alternative to --spec)")
         .option("-p, --prompt <text>", "Inline task text (alias for --task)")
         .option("--config <path>", "Path to orca config file")
@@ -186,14 +194,25 @@ export function registerRunCommand(program) {
         .option("--on-task-fail <cmd>", "Shell hook command for onTaskFail")
         .option("--on-complete <cmd>", "Shell hook command for onComplete")
         .option("--on-error <cmd>", "Shell hook command for onError")
-        .action(async (commandOptions) => {
-        const inlineTask = commandOptions.task ?? commandOptions.prompt;
-        if (!commandOptions.spec && !inlineTask) {
+        .action(async (goal, commandOptions) => {
+        const normalizedOptions = {
+            ...commandOptions,
+            ...(goal !== undefined ? { goal } : {})
+        };
+        const inlineTask = normalizedOptions.task ?? normalizedOptions.prompt ?? normalizedOptions.goal;
+        const inputSpecPath = normalizedOptions.spec ?? normalizedOptions.plan;
+        if (normalizedOptions.goal !== undefined && (normalizedOptions.task || normalizedOptions.prompt)) {
+            throw new Error("positional goal and --task/--prompt are mutually exclusive");
+        }
+        if (normalizedOptions.goal !== undefined && inputSpecPath) {
+            throw new Error("positional goal and --spec/--plan are mutually exclusive");
+        }
+        if (!inputSpecPath && !inlineTask) {
             throw new Error("One of --spec, --task, or --prompt (-p) must be provided.");
         }
-        if (commandOptions.spec && inlineTask) {
+        if (inputSpecPath && inlineTask) {
             throw new Error("--spec is mutually exclusive with --task / --prompt.");
         }
-        await runCommandHandler(commandOptions);
+        await runCommandHandler(normalizedOptions);
     });
 }

package/dist/cli/commands/status.js

@@ -1,4 +1,5 @@
 import { RunStore } from "../../state/store.js";
+import { getLastRun } from "../../utils/last-run.js";
 import { formatRunSummaryTable, listRuns } from "./list.js";
 function createStore() {
     const runsDir = process.env.ORCA_RUNS_DIR;
@@ -53,6 +54,16 @@ async function printDetailedRun(run) {
     console.log(formatTaskTable(run.tasks));
 }
 export async function statusCommandHandler(options) {
+    if (options.last) {
+        const store = createStore();
+        const lastRun = await getLastRun(store);
+        if (!lastRun) {
+            console.error("No runs found.");
+            process.exitCode = 1;
+            return;
+        }
+        options.run = lastRun.runId;
+    }
     if (!options.run) {
         const runs = await listRuns();
         if (runs.length === 0) {
@@ -77,6 +88,7 @@ export function registerStatusCommand(program) {
         .command("status")
         .description("Show run status or list all runs")
         .option("--run <run-id>", "Run ID to inspect")
+        .option("--last", "Use the most recent run")
         .option("--config <path>", "Path to orca config file")
         .action(async (options) => statusCommandHandler(options));
 }

package/dist/cli/index.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import { Command } from "commander";
+import { registerAnswerCommand } from "./commands/answer.js";
 import { registerCancelCommand } from "./commands/cancel.js";
+import { registerHelpCommand } from "./commands/help.js";
 import { registerListCommand } from "./commands/list.js";
+import { registerPrCommand } from "./commands/pr/index.js";
 import { registerPlanCommand } from "./commands/plan.js";
 import { registerPrFinalizeCommand } from "./commands/pr-finalize.js";
 import { registerResumeCommand } from "./commands/resume.js";
@@ -9,13 +12,16 @@ import { registerRunCommand } from "./commands/run.js";
 import { registerSetupCommand } from "./commands/setup.js";
 import { registerStatusCommand } from "./commands/status.js";
 const program = new Command();
-program.name("orca").description("Orca CLI: coordinated agent run harness").version("0.1.0");
+program.name("orca").description("Orca CLI: coordinated agent run harness").version("0.2.0");
 registerRunCommand(program);
+registerAnswerCommand(program);
 registerPlanCommand(program);
 registerStatusCommand(program);
 registerListCommand(program);
 registerResumeCommand(program);
 registerCancelCommand(program);
+registerPrCommand(program);
 registerPrFinalizeCommand(program);
 registerSetupCommand(program);
+registerHelpCommand(program);
 await program.parseAsync(process.argv);

package/dist/core/config-loader.js

@@ -1,5 +1,6 @@
 import { constants as fsConstants } from "node:fs";
 import { access } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 function isObject(value) {
@@ -51,3 +52,69 @@ export async function loadConfig(configPath) {
     const configCandidate = "default" in importedModule ? importedModule.default : importedModule;
     return coerceConfig(configCandidate);
 }
+const TOP_LEVEL_SCALARS = ["runsDir", "sessionLogs", "maxRetries", "anthropicApiKey", "openaiApiKey"];
+export function mergeConfigs(...configs) {
+    const presentConfigs = configs.filter((config) => config !== undefined);
+    if (presentConfigs.length === 0) {
+        return undefined;
+    }
+    const merged = {};
+    for (const config of presentConfigs) {
+        for (const key of TOP_LEVEL_SCALARS) {
+            if (key in config) {
+                merged[key] = config[key];
+            }
+        }
+        if (merged.claude !== undefined || config.claude !== undefined) {
+            merged.claude = { ...merged.claude, ...config.claude };
+        }
+        if (merged.codex !== undefined || config.codex !== undefined) {
+            merged.codex = { ...merged.codex, ...config.codex };
+        }
+        if (merged.pr !== undefined || config.pr !== undefined) {
+            merged.pr = { ...merged.pr, ...config.pr };
+        }
+        if (merged.hooks !== undefined || config.hooks !== undefined) {
+            merged.hooks = { ...merged.hooks, ...config.hooks };
+        }
+        if (merged.hookCommands !== undefined || config.hookCommands !== undefined) {
+            merged.hookCommands = { ...merged.hookCommands, ...config.hookCommands };
+        }
+    }
+    return merged;
+}
+async function loadOptionalConfig(configPath) {
+    const resolvedPath = path.resolve(configPath);
+    try {
+        await access(resolvedPath, fsConstants.R_OK);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+    return loadConfig(resolvedPath);
+}
+export async function resolveConfigFromPaths(globalConfigPath, projectConfigPath, cliConfigPath) {
+    const globalConfig = await loadOptionalConfig(globalConfigPath);
+    const projectConfig = await loadOptionalConfig(projectConfigPath);
+    const cliConfig = await loadConfig(cliConfigPath);
+    return mergeConfigs(globalConfig, projectConfig, cliConfig);
+}
+export async function resolveConfig(cliConfigPath) {
+    const globalConfigPath = path.join(os.homedir(), ".orca", "config.js");
+    const projectJsConfigPath = path.join(process.cwd(), "orca.config.js");
+    const projectTsConfigPath = path.join(process.cwd(), "orca.config.ts");
+    let projectConfigPath = projectJsConfigPath;
+    try {
+        await access(projectJsConfigPath, fsConstants.R_OK);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+        projectConfigPath = projectTsConfigPath;
+    }
+    return resolveConfigFromPaths(globalConfigPath, projectConfigPath, cliConfigPath);
+}

package/dist/core/task-runner.js

@@ -1,3 +1,5 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
 import { executeTask } from "../agents/claude/session.js";
 import { getRunnable, validateDAG } from "./dependency-graph.js";
 import { shouldRetry } from "./retry-policy.js";
@@ -38,6 +40,47 @@ function stripOptionalFields(task, fields) {
 function hasPendingTasks(tasks) {
     return tasks.some((task) => task.status === "pending" || task.status === "in_progress");
 }
+function buildSessionSummary(run) {
+    const taskRows = run.tasks.length === 0
+        ? "| (none) | - | - | - | - |\n"
+        : run.tasks
+            .map((task) => {
+            return `| ${task.id} | ${task.name} | ${task.status} | ${task.startedAt ?? "-"} | ${task.finishedAt ?? "-"} |`;
+        })
+            .join("\n");
+    return [
+        `# Run ${run.runId}`,
+        "",
+        `- Run ID: \`${run.runId}\``,
+        `- Spec Path: \`${run.specPath}\``,
+        `- Status: \`${run.overallStatus}\``,
+        `- Created At: \`${run.createdAt}\``,
+        `- Updated At: \`${run.updatedAt}\``,
+        "",
+        "## Tasks",
+        "",
+        "| ID | Name | Status | Started At | Finished At |",
+        "| --- | --- | --- | --- | --- |",
+        taskRows,
+        ""
+    ].join("\n");
+}
+async function writeSessionSummary(store, runId, sessionLogsDir) {
+    if (!sessionLogsDir) {
+        return;
+    }
+    try {
+        const run = await store.getRun(runId);
+        if (!run) {
+            throw new Error(`Run not found while writing session summary: ${runId}`);
+        }
+        await fs.mkdir(sessionLogsDir, { recursive: true });
+        await fs.writeFile(path.join(sessionLogsDir, `${runId}.md`), buildSessionSummary(run), "utf8");
+    }
+    catch (error) {
+        console.error(`Warning: failed to write session summary for ${runId}: ${toErrorMessage(error)}`);
+    }
+}
 export async function runTaskRunner(options) {
     const emitHook = options.emitHook ?? defaultEmitHook;
     const executeTaskFn = options.executeTask ?? executeTaskImpl;
@@ -68,6 +111,7 @@ export async function runTaskRunner(options) {
                     timestamp: new Date().toISOString(),
                     metadata: { overallStatus: "cancelled" }
                 });
+                await writeSessionSummary(store, runId, config?.sessionLogs);
                 return;
             }
             const runnable = getRunnable(run.tasks);
@@ -92,6 +136,7 @@ export async function runTaskRunner(options) {
                         timestamp: completedAt,
                         metadata: { overallStatus: "completed" }
                     });
+                    await writeSessionSummary(store, runId, config?.sessionLogs);
                     return;
                 }
                 if (hasFailedTask) {
@@ -113,6 +158,7 @@ export async function runTaskRunner(options) {
                         error: failureMessage,
                         metadata: { overallStatus: "failed" }
                     });
+                    await writeSessionSummary(store, runId, config?.sessionLogs);
                     return;
                 }
                 if (hasCancelledTask) {
@@ -124,6 +170,7 @@ export async function runTaskRunner(options) {
                         timestamp: new Date().toISOString(),
                         metadata: { overallStatus: "cancelled" }
                     });
+                    await writeSessionSummary(store, runId, config?.sessionLogs);
                     return;
                 }
                 if (hasPendingTasks(run.tasks)) {
@@ -257,6 +304,7 @@ export async function runTaskRunner(options) {
             error: errorMessage,
             metadata: { overallStatus: "failed" }
         });
+        await writeSessionSummary(store, runId, config?.sessionLogs);
         throw error;
     }
 }

package/dist/state/schema.js

@@ -38,7 +38,14 @@ export const RunStatusSchema = z.object({
     specPath: z.string(),
     createdAt: z.string(),
     updatedAt: z.string(),
-    overallStatus: z.enum(["planning", "running", "completed", "failed", "cancelled"]),
+    overallStatus: z.enum([
+        "planning",
+        "running",
+        "waiting_for_answer",
+        "completed",
+        "failed",
+        "cancelled"
+    ]),
     tasks: z.array(TaskSchema),
     milestones: z.array(z.string()),
     errors: z.array(ErrorEntrySchema),

package/dist/utils/gh.js

@@ -0,0 +1,35 @@
+function decodeStream(stream) {
+    if (!stream) {
+        return Promise.resolve("");
+    }
+    return new Response(stream).text();
+}
+export async function checkGhCli() {
+    try {
+        const proc = Bun.spawn(["which", "gh"], {
+            stdout: "pipe",
+            stderr: "pipe"
+        });
+        const exitCode = await proc.exited;
+        return exitCode === 0;
+    }
+    catch {
+        return false;
+    }
+}
+export async function runGh(args) {
+    const proc = Bun.spawn(["gh", ...args], {
+        stdout: "pipe",
+        stderr: "pipe"
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+        decodeStream(proc.stdout),
+        decodeStream(proc.stderr),
+        proc.exited
+    ]);
+    return {
+        stdout,
+        stderr,
+        exitCode
+    };
+}

package/dist/utils/last-run.js

@@ -0,0 +1,7 @@
+export async function getLastRun(store) {
+    const runs = await store.listRuns();
+    if (runs.length === 0) {
+        return null;
+    }
+    return runs.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime())[0] ?? null;
+}

package/dist/utils/select-run.js

@@ -0,0 +1,18 @@
+import { select } from "@inquirer/prompts";
+export async function selectRun(store) {
+    if (!process.stdout.isTTY) {
+        return null;
+    }
+    const runs = await store.listRuns();
+    if (runs.length === 0) {
+        console.error("No runs found.");
+        return null;
+    }
+    const sorted = [...runs].sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+    const choices = sorted.map((run) => {
+        const prStatus = run.pr?.url ? (run.pr.finalizedAt ? "published" : "draft PR") : "no PR";
+        const label = `${run.runId}  [${run.overallStatus}]  ${prStatus}`;
+        return { name: label, value: run.runId };
+    });
+    return select({ message: "Select a run:", choices });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orcastrator",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "bin": {
     "orca": "./dist/cli/index.js"
@@ -17,9 +17,10 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.47",
+    "@inquirer/prompts": "^8.2.1",
     "chalk": "^5.3.0",
-    "orca-codex-client": "^0.1.0",
     "commander": "^13.1.0",
+    "orca-codex-client": "^0.1.0",
     "zod": "^3.24.1"
   },
   "devDependencies": {