@tryarcanist/cli 0.1.140 → 0.1.142

package/README.md

@@ -132,7 +132,7 @@ arcanist sessions create your-org/your-repo "retry-safe create" --idempotency-ke
 
 `--backend` picks the agent runtime backend: `codex` (default) or `claude_code`. `--model` must be valid for the chosen backend — codex runs OpenAI models (`gpt-5.4` default, `gpt-5.5`), `claude_code` runs Anthropic models (`claude-opus-4-8` default, `claude-sonnet-4-6`) — and the CLI rejects a mismatch before any network call. `claude_code` sessions require an Anthropic API key configured in Settings.
 
-`--wait` blocks until the created prompt finishes, prints the resulting PR/branch line in human-readable mode when it is already available, and exits non-zero if the prompt finishes with `status: failed`, making it suitable for cron or other schedulers that alert on command failure. `--poll-interval <ms>` tunes the completion check frequency.
+`--wait` blocks until the created prompt finishes, prints the resulting PR/branch line in human-readable mode when it is already available, and exits non-zero if the prompt finishes with `status: failed`, making it suitable for cron or other schedulers that alert on command failure. JSON mode waits quietly and prints the create payload after the prompt completes successfully. `--poll-interval <ms>` tunes the completion check frequency.
 
 Use `--base-branch <branch>` to target a non-default base branch. The CLI only validates that the branch value is non-empty; branch existence is checked later by the session runtime.
 
@@ -144,9 +144,9 @@ Repeatable `--uploaded-file <path>` flags attach local UTF-8 text files to the p
 
 `--idempotency-key <uuid>` is for manually retrying a create request that may have reached the server. The CLI derives separate session and prompt idempotency keys from the provided value.
 
-`--onboarding` creates an onboarding session: the agent authors the repo's `.arcanist.json`, `.arcanist/` runtime files, `ARCANIST.md`, and conditionally `.arcanist/sandbox.yaml` + `.arcanist/sandbox.layer.Dockerfile` (when the base sandbox lacks a needed toolchain), proves what it can inside its sandbox, and opens the setup PR ready for review. Team use; not part of the external API surface.
+`--onboarding` creates an onboarding session: the agent authors the repo's `.arcanist.json`, `.arcanist/` runtime files, `ARCANIST.md`, and conditionally `.arcanist/sandbox.yaml` + `.arcanist/sandbox.layer.Dockerfile` (when the base sandbox lacks a needed toolchain), proves what it can inside its sandbox, and opens the setup PR ready for review. The onboarding behavior is driven by the bridge's canonical onboarding playbook, not the prompt, so `--onboarding` needs no prompt: `arcanist sessions create <repo> --onboarding --wait`. Any prompt supplied alongside `--onboarding` is ignored. Team use; not part of the external API surface.
 
-JSON mode returns `{sessionId, sessionUrl?, repoUrl, model?, agentRuntimeBackend?, reasoningEffort?, baseBranch?, promptId?}`. `sessionUrl` is emitted only when the server returns it; `agentRuntimeBackend` only when `--backend` is passed.
+JSON mode returns `{sessionId, sessionUrl?, repoUrl, model?, agentRuntimeBackend?, reasoningEffort?, baseBranch?, startBranch?, onboarding?, promptId?}`. `sessionUrl` is emitted only when the server returns it; `agentRuntimeBackend` only when `--backend` is passed. With `--wait`, JSON mode also includes best-effort result fields when available: `prUrl?`, `publishedBranch?`, and `lastBranch?`.
 
 ### `arcanist sessions send <session-id> [prompt]`
 
@@ -170,7 +170,7 @@ arcanist sessions stop abc123
 arcanist sessions stop abc123 --json
 ```
 
-JSON mode returns `{sessionId, status}` where status is `stopping` or `already_stopped`.
+JSON mode returns `{sessionId, status}`. `status` is the server stop status or, on a 409 stop-block, the block reason; it is an open set. Known values include `stopping`, `stopped`, `already_stopped`, `not_stoppable`, and lifecycle phase names.
 
 ### `arcanist sessions get <session-id>`
 
@@ -216,7 +216,13 @@ arcanist sessions events abc123 --follow --json
 
 `--after` and `--before` are aliases for `--after-sequence` and `--before-sequence`.
 
-Follow mode emits NDJSON, one replay event per line, until the session becomes idle.
+JSON mode without `--follow` returns one JSON object from `/events/history`: `{events: [...], ...}`. Canonical events carry `phase`.
+
+Follow mode emits NDJSON, one `{sequence, type, data}` object per line, until the session becomes idle. Actionable follow-mode signals:
+
+- PR opened or updated: `pr_created` / `pr_updated`; URL at `data.prUrl`.
+- Waiting for human input: `question`; question text at `data.question`.
+- Terminal: `prompt_completed`, `prompt_failed`, and `session_idle`. Follow JSON mode suppresses lifecycle `status` frames, so key on these event names rather than `waiting_for_input`.
 
 ### `arcanist sessions transcript <session-id>`
 
@@ -329,15 +335,12 @@ arcanist sessions create your-org/your-repo "verify the new rate limiter is acti
 
 For cron, prefer `ARCANIST_TOKEN` or a logged-in `~/.arcanist/config.json` over passing `--token` on the command line.
 
-To capture the PR URL after a successful run, use `create --wait` for the exit code, then read the session state:
+To capture the PR URL after a successful run, read the best-effort result fields from `create --wait --json`:
 
 ```bash
-SESSION_ID=$(arcanist sessions create your-org/your-repo "fix the flaky test" --wait --json | jq -r .sessionId)
-for _ in {1..20}; do
-  PR_URL=$(arcanist sessions get "$SESSION_ID" --json | jq -r '.session.prUrl // empty')
-  [ -n "$PR_URL" ] && break
-  sleep 5
-done
+RESULT=$(arcanist sessions create your-org/your-repo "fix the flaky test" --wait --json)
+PR_URL=$(jq -r '.prUrl // empty' <<<"$RESULT")
+SESSION_ID=$(jq -r '.sessionId' <<<"$RESULT")
 [ -n "$PR_URL" ] || { echo "PR URL not ready for $SESSION_ID" >&2; exit 1; }
 ```
 

package/dist/index.js

@@ -83,7 +83,7 @@ function parseApiErrorBody(body) {
   }
 }
 function hintForHttpStatus(status) {
-  if (status === 401 || status === 403) return "Run `arcanist login` or set `ARCANIST_TOKEN`.";
+  if (status === 401 || status === 403) return "Run `arcanist auth login` or set `ARCANIST_TOKEN`.";
   if (status === 404) return "List sessions with `arcanist sessions list`.";
   if (status === 409) return "Check the current resource state and retry the command when it is ready.";
   if (status >= 500) return "Retry later or check the control-plane logs.";
@@ -172,7 +172,7 @@ function saveConfig(config) {
 function requireConfig(overrides) {
   const config = loadConfig(overrides);
   if (!config) {
-    throw new CliError("auth", "Not logged in.", { hint: "Run `arcanist login` or set `ARCANIST_TOKEN`." });
+    throw new CliError("auth", "Not logged in.", { hint: "Run `arcanist auth login` or set `ARCANIST_TOKEN`." });
   }
   return config;
 }
@@ -2051,9 +2051,7 @@ function stringField(value) {
   return typeof value === "string" && value.trim() ? value : null;
 }
 function formatSessionResult(session) {
-  const prUrl = stringField(session.prUrl);
-  const publishedBranch = stringField(session.publishedBranch);
-  const lastBranch = stringField(session.lastBranch);
+  const { prUrl, publishedBranch, lastBranch } = extractSessionResultFields(session);
   const baseBranch = stringField(session.baseBranch);
   const branch = publishedBranch ?? (lastBranch && lastBranch !== baseBranch ? lastBranch : null);
   if (prUrl) {
@@ -2064,6 +2062,16 @@ function formatSessionResult(session) {
   }
   return null;
 }
+function extractSessionResultFields(session) {
+  const result = {};
+  const prUrl = stringField(session.prUrl);
+  const publishedBranch = stringField(session.publishedBranch);
+  const lastBranch = stringField(session.lastBranch);
+  if (prUrl) result.prUrl = prUrl;
+  if (publishedBranch) result.publishedBranch = publishedBranch;
+  if (lastBranch) result.lastBranch = lastBranch;
+  return result;
+}
 function latestCompletedPromptResult(prompts) {
   for (let i = prompts.length - 1; i >= 0; i--) {
     if (prompts[i].status === "completed") return prompts[i].result;
@@ -2501,6 +2509,8 @@ function validateRepoUrl(url) {
   return `Invalid repo URL: "${url}". Expected a GitHub URL (https://github.com/owner/repo) or owner/repo shorthand.`;
 }
 var PROMPT_TERMINAL_STATUSES = /* @__PURE__ */ new Set(["completed", "failed"]);
+var RESULT_FETCH_ATTEMPTS = 5;
+var ONBOARDING_PROMPT = "Onboard this repository onto Arcanist.";
 function selectCreatedPrompt(prompts, promptId) {
   if (prompts.length === 0) return null;
   if (promptId) {
@@ -2562,6 +2572,25 @@ async function waitForCreatedPrompt(sessionId, promptId, sessionUrl, pollInterva
     );
   }
 }
+function unwrapSessionState(payload) {
+  return payload.session && typeof payload.session === "object" ? payload.session : payload;
+}
+async function fetchSessionResultFields(config, sessionId) {
+  const sessionPayload = await apiFetch(config, `/api/sessions/${sessionId}`);
+  return extractSessionResultFields(unwrapSessionState(sessionPayload));
+}
+async function fetchSettledSessionResultFields(config, sessionId, pollIntervalMs) {
+  const effectivePollIntervalMs = Math.max(pollIntervalMs, MIN_WATCH_POLL_INTERVAL_MS);
+  let latest = {};
+  for (let attempt = 0; attempt < RESULT_FETCH_ATTEMPTS; attempt++) {
+    latest = await fetchSessionResultFields(config, sessionId);
+    if (latest.prUrl || latest.publishedBranch) return latest;
+    if (attempt < RESULT_FETCH_ATTEMPTS - 1) {
+      await sleep(effectivePollIntervalMs);
+    }
+  }
+  return latest;
+}
 async function createCommand(repoUrl, promptArg, options, command) {
   const runtime = getRuntimeOptions(command, options);
   const config = requireConfig(runtime);
@@ -2582,7 +2611,7 @@ async function createCommand(repoUrl, promptArg, options, command) {
       );
     }
   }
-  const prompt = await resolvePromptInput(promptArg, options);
+  const prompt = options.onboarding ? ONBOARDING_PROMPT : await resolvePromptInput(promptArg, options);
   const waitPollIntervalMs = options.wait ? parsePollInterval(options.pollInterval) : null;
   const repoError = validateRepoUrl(repoUrl);
   if (repoError) {
@@ -2615,6 +2644,7 @@ async function createCommand(repoUrl, promptArg, options, command) {
   });
   const sessionId = sessionData.sessionId;
   let promptId;
+  let waitResultFields = {};
   try {
     const promptData = await apiFetch(
       config,
@@ -2643,10 +2673,16 @@ async function createCommand(repoUrl, promptArg, options, command) {
       if (sessionData.sessionUrl) console.log(`URL: ${sessionData.sessionUrl}`);
     }
     await waitForCreatedPrompt(sessionId, promptId, sessionData.sessionUrl, waitPollIntervalMs, runtime, command);
+    if (isJson(command, options)) {
+      try {
+        waitResultFields = await fetchSettledSessionResultFields(config, sessionId, waitPollIntervalMs);
+      } catch {
+      }
+    }
     if (!isJson(command, options)) {
       try {
         const sessionPayload = await apiFetch(config, `/api/sessions/${sessionId}`);
-        const sessionState = sessionPayload.session && typeof sessionPayload.session === "object" ? sessionPayload.session : sessionPayload;
+        const sessionState = unwrapSessionState(sessionPayload);
         const resultLine = formatSessionResult(sessionState);
         if (resultLine) console.log(resultLine);
       } catch {
@@ -2664,12 +2700,14 @@ async function createCommand(repoUrl, promptArg, options, command) {
     if (startBranch) output.startBranch = startBranch;
     if (options.onboarding) output.onboarding = true;
     if (promptId) output.promptId = promptId;
+    Object.assign(output, waitResultFields);
     writeJson(output);
     return;
   }
   if (options.wait) return;
   console.log(`Session: ${sessionId}`);
   if (sessionData.sessionUrl) console.log(`URL: ${sessionData.sessionUrl}`);
+  console.log(`Follow with: arcanist sessions events ${sessionId} --follow --json`);
 }
 
 // src/commands/egress.ts
@@ -4355,6 +4393,11 @@ Examples:
   printf "fix bug" | arcanist sessions create https://github.com/org/repo --prompt-stdin --json
   printf "fix bug" | arcanist sessions create https://github.com/org/repo --prompt-stdin --wait
   arcanist sessions create https://github.com/org/repo - --json | jq -r .sessionId | xargs -I{} arcanist sessions events {} --follow --json
+
+JSON:
+JSON mode returns {sessionId, sessionUrl?, repoUrl, model?, agentRuntimeBackend?, reasoningEffort?, baseBranch?, startBranch?, onboarding?, promptId?}
+--wait --json also includes best-effort result fields when available: prUrl?, publishedBranch?, lastBranch?
+  Follow async progress with: arcanist sessions events <session-id> --follow --json
 `
   );
 }
@@ -4370,6 +4413,9 @@ Examples:
   arcanist sessions send <session-id> "also update tests"
   arcanist sessions send <session-id> "use this log" --uploaded-file failing.log
   printf "also update tests" | arcanist sessions send <session-id> --prompt-stdin --json
+
+JSON:
+JSON mode returns {sessionId, promptId?}
 `
   );
 }
@@ -4404,6 +4450,10 @@ sessions.command("stop").description("Stop the active run for a session").argume
 Examples:
   arcanist sessions stop <session-id>
   arcanist sessions stop <session-id> --json
+
+JSON:
+JSON mode returns {sessionId, status}
+  status is the server stop status or 409 stop-block reason. Known values include stopping, stopped, already_stopped, not_stoppable, and lifecycle phase names.
 `
 ).action((sessionId, options, command) => stopCommand(sessionId, options, command));
 sessions.command("get").description("Get session details").argument("<session-id>", "Session ID").addHelpText(
@@ -4412,6 +4462,9 @@ sessions.command("get").description("Get session details").argument("<session-id
 Examples:
   arcanist sessions get <session-id>
   arcanist sessions get <session-id> --json
+
+JSON:
+JSON mode returns the raw session payload. Result fields are at .session.prUrl, .session.publishedBranch, and .session.lastBranch.
 `
 ).action((sessionId, options, command) => getSessionCommand(sessionId, options, command));
 sessions.command("list").description("List sessions").option("--status <status>", "Filter by session status").option("--scope <scope>", "Session scope: mine or business").option("--search <query>", "Search session titles and repo metadata").option("--repo <repo>", "Filter by repo metadata").option("--limit <n>", "Maximum sessions to return").option("--cursor <cursor>", "Pagination cursor").addHelpText(
@@ -4421,6 +4474,9 @@ Examples:
   arcanist sessions list
   arcanist sessions list --status idle --json
   arcanist sessions list --search "architect agent" --repo owner/repo
+
+JSON:
+JSON mode returns {sessions, nextCursor}
 `
 ).action((options, command) => listSessionsCommand(options, command));
 sessions.command("search").description("Search sessions by title and repo metadata").argument("<query>", "Search query").option("--status <status>", "Filter by session status").option("--scope <scope>", "Session scope: mine or business").option("--repo <repo>", "Filter by repo metadata").option("--limit <n>", "Maximum sessions to return").option("--cursor <cursor>", "Pagination cursor").addHelpText(
@@ -4429,6 +4485,9 @@ sessions.command("search").description("Search sessions by title and repo metada
 Examples:
   arcanist sessions search "architect agent"
   arcanist sessions search "mcp debugging" --repo owner/repo --json
+
+JSON:
+JSON mode returns {sessions, nextCursor}
 `
 ).action((query, options, command) => searchSessionsCommand(query, options, command));
 sessions.command("events").description("Read or follow session replay events").argument("<session-id>", "Session ID").option("--after-sequence <n>", "Return events after this sequence").option("--after <n>", "Alias for --after-sequence").option("--before-sequence <n>", "Return events before this sequence").option("--before <n>", "Alias for --before-sequence").option("--prompt-id <id>", "Filter events by prompt ID").option("--limit <n>", "Maximum events to return").option("--follow", "Follow events until the session is idle").option("--poll-interval <ms>", "Polling interval in milliseconds", String(DEFAULT_WATCH_POLL_INTERVAL_MS)).addHelpText(
@@ -4439,6 +4498,11 @@ Examples:
   arcanist sessions events <session-id> --after-sequence 540 --limit 250 --json
   arcanist sessions events <session-id> --after 540 --limit 250 --json
   arcanist sessions events <session-id> --follow --json
+
+JSON:
+JSON mode without --follow returns one JSON object from /events/history: {events: [...], ...}; canonical events carry phase.
+--follow --json emits NDJSON, one {sequence, type, data} object per line.
+  Actionable follow types: pr_created/pr_updated use data.prUrl; question uses data.question; terminal types are prompt_completed, prompt_failed, and session_idle.
 `
 ).action((sessionId, options, command) => sessionEventsCommand(sessionId, options, command));
 sessions.command("transcript").description("Render a session transcript").argument("<session-id>", "Session ID").addHelpText(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryarcanist/cli",
-  "version": "0.1.140",
+  "version": "0.1.142",
   "description": "CLI for Arcanist — create and manage coding agent sessions",
   "type": "module",
   "bin": {