@junoflow/cli 0.15.0 → 0.17.0

package/src/api.js

@@ -281,9 +281,11 @@ export class JunoClient {
   async callTool(name, input) {
     const path = `/api/tools/${encodeURIComponent(name)}`;
     const res = await this.#request('POST', path, input);
+    const skills = skillsHeader(res);
     if (res.status === 422) {
       throw new UsageError(
-        `invalid input for ${name}: ${validationDetail(res)}`
+        `invalid input for ${name}: ${validationDetail(res)}` +
+          (skills.length ? `\n${skillsPointer(skills)}` : '')
       );
     }
     if (res.status === 404) {
@@ -293,7 +295,7 @@ export class JunoClient {
       );
     }
     if (!res.ok) throw failure('POST', path, res);
-    return { result: jsonBody('POST', path, res), text: res.text };
+    return { result: jsonBody('POST', path, res), text: res.text, skills };
   }
 
   /**
@@ -306,8 +308,8 @@ export class JunoClient {
   }
 
   /**
-   * GET /api/skills — `{skills: [{name, description}], agent_skill_version}`,
-   * sorted by name. `authoring` (`flow` or `integration`) narrows it to the
+   * GET /api/skills — `{skills: [{name, description, applies_to}]}`, sorted
+   * by name. `authoring` (`flow` or `integration`) narrows it to the
    * skills for writing that kind of working copy.
    */
   async listSkills({ authoring } = {}) {
@@ -318,12 +320,20 @@ export class JunoClient {
   }
 
   /**
-   * GET /api/agent-skill — `{version, skill_md, agents_md, permissions,
-   * working_copy_permissions}`: the skill a coding agent installs and the
-   * permission rules that go with it, both rendered by the server.
+   * GET /api/agent-primer — `{body}`: the markdown `juno --help` prints
+   * between its usage lines and the command listing, rendered by the server.
    */
-  async getAgentSkill() {
-    return this.#json('GET', '/api/agent-skill');
+  async getAgentPrimer() {
+    return this.#json('GET', '/api/agent-primer');
+  }
+
+  /**
+   * GET /api/agent-permissions — `{read, change, working_copy: {read,
+   * change}}`: Claude Code permission rules for the juno commands and a
+   * working copy's npm scripts, by effect, rendered by the server.
+   */
+  async getAgentPermissions() {
+    return this.#json('GET', '/api/agent-permissions');
   }
 
   /**
@@ -456,6 +466,49 @@ export class JunoClient {
     return jsonBody('GET', path, res);
   }
 
+  /**
+   * GET /api/approvals/{id} — one approval as it stands, or null when there
+   * is none. Readable at read scope, so the key that asked can poll it.
+   */
+  async getApproval(id) {
+    const path = `/api/approvals/${encodeURIComponent(id)}`;
+    const res = await this.#request('GET', path);
+    if (res.status === 404) return null;
+    if (!res.ok) throw failure('GET', path, res);
+    return jsonBody('GET', path, res);
+  }
+
+  /**
+   * rest is one call to a REST route the CLI fronts without a tool (the
+   * session, whoami and version commands): the answer's JSON body, or a
+   * UserError carrying the server's words — a 404 as `notFound` when given,
+   * else just those words, since it is the id the person typed that is
+   * unknown.
+   */
+  async rest(method, path, body, { notFound } = {}) {
+    const res = await this.#request(method, path, body);
+    if (res.status === 404) {
+      throw new UserError(notFound ?? problemDetail(res));
+    }
+    if (res.status === 422) throw new UsageError(validationDetail(res));
+    return this.#answer(method, path, res);
+  }
+
+  /**
+   * events reads a server-sent event stream as it arrives, yielding
+   * `{event, data}` with data parsed as JSON; it ends when the server closes
+   * the stream or `signal` aborts. A non-2xx answer is the route's failure.
+   */
+  async *events(path, { signal } = {}) {
+    const res = await this.#send('GET', path, undefined, signal);
+    if (!res.ok) {
+      const answer = await this.#read(res);
+      if (answer.status === 404) throw new UserError(problemDetail(answer));
+      throw failure('GET', path, answer);
+    }
+    yield* sse(res.body, this.target, signal);
+  }
+
   /**
    * #request sends a request and reads its whole answer. It throws only when
    * there is no answer at all; every status comes back to the caller, which
@@ -474,7 +527,7 @@ export class JunoClient {
    * request to its sign-in page. Following it would hand the caller that
    * page's HTML as a 200.
    */
-  async #send(method, path, body) {
+  async #send(method, path, body, signal) {
     const url = `${this.target}${path}`;
     // Every request carries the header, the existing commands' included:
     // one client, one header.
@@ -488,6 +541,7 @@ export class JunoClient {
         headers,
         body: body ? JSON.stringify(body) : undefined,
         redirect: 'manual',
+        signal,
       });
     } catch (err) {
       throw new UnreachableError(
@@ -527,6 +581,7 @@ export class JunoClient {
       ok: res.ok,
       status: res.status,
       statusText: res.statusText,
+      headers: res.headers,
       text,
       parsed,
     };
@@ -574,6 +629,60 @@ async function* ndjson(body, target) {
   yield* lines(true);
 }
 
+/**
+ * sse reads a text/event-stream body: blank-line separated events of
+ * `event:` and `data:` lines, each data parsed as JSON. An abort ends it
+ * quietly; a connection that drops is an UnreachableError.
+ */
+async function* sse(body, target, signal) {
+  const decoder = new TextDecoder();
+  let buffered = '';
+  const events = function* (final) {
+    buffered = buffered.replace(/\r\n/g, '\n');
+    let end;
+    while (
+      (end = buffered.indexOf('\n\n')) >= 0 ||
+      (final && buffered.trim())
+    ) {
+      const block = end >= 0 ? buffered.slice(0, end) : buffered;
+      buffered = end >= 0 ? buffered.slice(end + 2) : '';
+      let event = 'message';
+      const data = [];
+      for (const line of block.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim();
+        else if (line.startsWith('data:')) data.push(line.slice(5).trimStart());
+      }
+      if (!data.length) continue;
+      const text = data.join('\n');
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        throw new UserError(
+          `the stream sent an event that is not JSON: ${text}`
+        );
+      }
+      yield { event, data: parsed };
+    }
+  };
+  try {
+    for await (const chunk of body) {
+      buffered += decoder.decode(chunk, { stream: true });
+      yield* events(false);
+    }
+  } catch (err) {
+    if (err instanceof UserError || signal?.aborted) {
+      if (signal?.aborted) return;
+      throw err;
+    }
+    throw new UnreachableError(
+      `lost the connection to Juno at ${target}: ${err.message}`
+    );
+  }
+  buffered += decoder.decode();
+  yield* events(true);
+}
+
 /**
  * jsonBody is a 2xx answer's parsed body, which every route this client calls
  * answers as a JSON object. Anything else came from something other than
@@ -584,17 +693,47 @@ async function* ndjson(body, target) {
 function jsonBody(method, path, res) {
   if (res.parsed === null || typeof res.parsed !== 'object') {
     throw new UserError(
-      `${method} ${path} answered something that is not JSON: ${res.text.trim()}`
+      `${method} ${path} answered something that is not JSON: ${briefText(res)}`
     );
   }
   return res.parsed;
 }
 
+/**
+ * skillsHeader is X-Juno-Skills, the skills the gateway names beside a call
+ * the tool refused (a 422, or a result with a string error), or [] when it
+ * sent none. The server decides which skills apply; the CLI only prints them.
+ */
+function skillsHeader(res) {
+  const value = res.headers?.get?.('x-juno-skills') ?? '';
+  return value.split(/\s+/).filter(Boolean);
+}
+
+/** The last stderr line after a refused call: what to read before retrying. */
+export function skillsPointer(skills) {
+  return `see: juno skill ${skills.join(' ')}`;
+}
+
 /** The server's own words in an error answer: Huma's `detail`, else the body. */
 function problemDetail(res) {
-  return (
-    res.parsed?.detail || res.parsed?.title || res.text.trim() || res.statusText
-  );
+  return res.parsed?.detail || res.parsed?.title || briefText(res);
+}
+
+const BRIEF_LIMIT = 200;
+
+/**
+ * briefText is a body that is not Juno's JSON, cut to one line: an HTML page
+ * (a proxy's, or an instance older than the route answering its web app) is
+ * named rather than printed, because its markup buries the one line that
+ * matters — the status and the route — under a screenful of tags, and other
+ * text is collapsed to one line of at most BRIEF_LIMIT characters.
+ */
+export function briefText(res) {
+  const text = (res.text ?? '').trim();
+  if (!text) return res.statusText || '(empty body)';
+  if (/^<(!doctype|html|head|body)\b/i.test(text)) return 'an HTML page';
+  const flat = text.replace(/\s+/g, ' ');
+  return flat.length > BRIEF_LIMIT ? `${flat.slice(0, BRIEF_LIMIT)}…` : flat;
 }
 
 /**
@@ -619,7 +758,7 @@ const UNAUTHORIZED_HINT =
  * `errors[]` instead, so those are appended.
  */
 function validationDetail(res) {
-  const parts = [res.parsed?.detail || res.text.trim() || res.statusText];
+  const parts = [res.parsed?.detail || briefText(res)];
   for (const e of res.parsed?.errors ?? []) {
     parts.push(e.location ? `${e.location}: ${e.message}` : e.message);
   }

package/src/authoring-skills.js

@@ -1,5 +1,3 @@
-import { warnIfStale } from './installed-skill.js';
-
 /**
  * The kinds of working copy with an authoring skill index, and the heading
  * each is printed under. The index itself is the server's
@@ -22,10 +20,9 @@ export function authoringHeading(kind) {
  * printAuthoringIndex prints a kind's authoring skills after `init` has
  * written the working copy, as `  <name> — <description>`. Fetching it is a
  * courtesy: the working copy is already on disk, so a failure is a note on
- * stderr, never a failed init. It also says when an installed agent skill is
- * stale, since the index carries the version the instance serves.
+ * stderr, never a failed init.
  */
-export async function printAuthoringIndex(kind, client, target, io) {
+export async function printAuthoringIndex(kind, client, io) {
   let index;
   try {
     index = await client.listSkills({ authoring: kind });
@@ -39,5 +36,4 @@ export async function printAuthoringIndex(kind, client, target, io) {
     io.log(authoringHeading(kind));
     for (const s of skills) io.log(`  ${s.name} — ${s.description}`);
   }
-  await warnIfStale(index, target, io);
 }

package/src/commands/app-init.js

@@ -41,6 +41,6 @@ export async function appInit(argv, io) {
   io.log('npm test');
   io.log('npm run check    # stores a draft and prints its preview URL');
   io.log('npm run deploy');
-  await printAuthoringIndex('app', client, target, io);
+  await printAuthoringIndex('app', client, io);
   return 0;
 }

package/src/commands/approval-wait.js

@@ -0,0 +1,215 @@
+import { connect } from '../api.js';
+import { UnreachableError, UsageError, UserError } from '../errors.js';
+import {
+  EXIT_FAILURE,
+  EXIT_INTERRUPTED,
+  EXIT_OK,
+  EXIT_PENDING,
+} from '../exit.js';
+
+export const APPROVAL_WAIT_USAGE =
+  'juno approval wait <approval-id> [--wait <seconds>]';
+
+/** How long a destructive command waits for a person by default. */
+export const DEFAULT_APPROVAL_WAIT_SECONDS = 300;
+
+/** How often the approval is read while waiting. */
+const POLL_MS = 2000;
+
+/**
+ * approvalWaitSeconds reads `--wait`: whole seconds, 0 meaning look once.
+ */
+export function approvalWaitSeconds(flag) {
+  if (flag === undefined) return DEFAULT_APPROVAL_WAIT_SECONDS;
+  if (!/^\d+$/.test(flag)) {
+    throw new UsageError(`--wait takes a number of seconds, got "${flag}"`);
+  }
+  return Number(flag);
+}
+
+/**
+ * `juno approval wait <id>` picks up a wait a destructive command left: it
+ * reads the approval and, while a person has not decided it, waits as the
+ * command did, then prints how it ended and exits the same way.
+ */
+export async function approvalWait(args, io) {
+  const [id, ...extra] = args._;
+  if (id === undefined || extra.length) {
+    throw new UsageError(`usage: ${APPROVAL_WAIT_USAGE}`);
+  }
+  const wait = approvalWaitSeconds(args.wait);
+  const { client, target } = await connect(args, io);
+  const a = await client.getApproval(id);
+  if (!a) throw new UserError(`no approval ${id}`);
+  const required = {
+    id: a.id,
+    url: approvalURL(`/approvals/${a.id}`, target),
+    summary: a.summary,
+    expires_at: a.expires_at,
+  };
+  return followApproval(required, {
+    client,
+    target,
+    wait,
+    io,
+    print: json(io),
+  });
+}
+
+/**
+ * followApproval is plan-cli-parity.md decision 11, and the one place the CLI
+ * interprets a result: a destructive tool answered `approval_required`, so
+ * it says on stderr what needs approving and where, then reads the approval
+ * until a person decided it or `wait` seconds ran out.
+ *
+ * - executed: the stored result, with `approval: {id, approved_by}` beside
+ *   it, exit 0 — or 1 when the result is a refusal, as the tool's own would be
+ * - failed, denied, expired: `{"error": …}`, exit 1
+ * - still pending: the `approval_required` answer again, exit 5
+ * - Ctrl-C: exit 130, the request left open
+ *
+ * `print` writes one JSON value to stdout (a `--jq` filter applies to it).
+ */
+export async function followApproval(
+  required,
+  { client, target, wait, io, print }
+) {
+  const id = required.id;
+  const url = approvalURL(required.url ?? `/approvals/${id}`, target);
+  const resume = `juno approval wait ${id}`;
+  io.warn(`Approval needed: ${required.summary}.`);
+  io.warn(`Approve or deny in Juno: ${url}`);
+
+  const interrupt = new AbortController();
+  const off = io.onInterrupt?.(() => interrupt.abort()) ?? (() => {});
+  try {
+    const now = io.now ?? Date.now;
+    const deadline = now() + wait * 1000;
+    let approval = await read(client, id, io);
+    if (approval?.status === 'pending' || approval?.status === 'approved') {
+      io.warn(
+        wait > 0
+          ? `waiting up to ${wait}s… (Ctrl-C leaves the request open: ${resume})`
+          : `not waiting (--wait 0); check later with: ${resume}`
+      );
+    }
+    while (!approval || !ended(approval.status)) {
+      const left = deadline - now();
+      if (left <= 0) break;
+      await sleep(Math.min(io.pollMs ?? POLL_MS, left), interrupt.signal);
+      if (interrupt.signal.aborted) {
+        io.warn(`stopped waiting; the request is still open: ${resume}`);
+        return EXIT_INTERRUPTED;
+      }
+      approval = (await read(client, id, io)) ?? approval;
+    }
+    if (!approval || !ended(approval.status)) {
+      await print({ approval_required: { ...required, url } });
+      io.warn(`still waiting for a person; keep waiting with: ${resume}`);
+      return EXIT_PENDING;
+    }
+    return outcome(approval, print);
+  } finally {
+    off();
+  }
+}
+
+/** The statuses an approval ends in; `approved` means its call is running. */
+function ended(status) {
+  return ['executed', 'failed', 'denied', 'expired'].includes(status);
+}
+
+/**
+ * read is one GET of the approval. A dropped connection is not the end of the
+ * wait — the next read may well get through — so it answers null and warns;
+ * an approval that does not exist is.
+ */
+async function read(client, id, io) {
+  try {
+    const a = await client.getApproval(id);
+    if (!a) throw new UserError(`no approval ${id}`);
+    return a;
+  } catch (err) {
+    if (!(err instanceof UnreachableError)) throw err;
+    io.warn(`${err.message}; still waiting`);
+    return null;
+  }
+}
+
+async function outcome(a, print) {
+  switch (a.status) {
+    case 'executed': {
+      await print(
+        withApproval(a.result, { id: a.id, approved_by: a.decided_by })
+      );
+      return typeof a.result?.error === 'string' ? EXIT_FAILURE : EXIT_OK;
+    }
+    case 'failed': {
+      // The tool refused (it answered an error, stored as the result), or the
+      // call could not run at all (the error alone).
+      const result =
+        a.result && typeof a.result === 'object' && !Array.isArray(a.result)
+          ? a.result
+          : { error: a.error };
+      if (typeof result.error !== 'string') result.error = a.error;
+      await print(
+        withApproval(result, {
+          id: a.id,
+          status: 'failed',
+          approved_by: a.decided_by,
+        })
+      );
+      return EXIT_FAILURE;
+    }
+    case 'denied':
+      await print({
+        error: `denied by ${a.decided_by}`,
+        approval: { id: a.id, status: 'denied' },
+      });
+      return EXIT_FAILURE;
+    default:
+      await print({
+        error: 'expired: nobody approved it within 24 hours',
+        approval: { id: a.id, status: 'expired' },
+      });
+      return EXIT_FAILURE;
+  }
+}
+
+/** The result with the approval beside it; a non-object result is wrapped. */
+function withApproval(result, approval) {
+  if (result && typeof result === 'object' && !Array.isArray(result)) {
+    return { ...result, approval };
+  }
+  return { result: result ?? null, approval };
+}
+
+/**
+ * The page an approval is decided on: the server's link, which is a bare path
+ * while the instance has no public URL — completed against the instance this
+ * CLI reached.
+ */
+export function approvalURL(url, target) {
+  return url.startsWith('/')
+    ? `${String(target).replace(/\/+$/, '')}${url}`
+    : url;
+}
+
+/** json prints a value as the CLI prints any result: indented on a TTY. */
+export function json(io) {
+  return async (value) =>
+    io.log(io.isTTY ? JSON.stringify(value, null, 2) : JSON.stringify(value));
+}
+
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const t = setTimeout(done, ms);
+    function done() {
+      clearTimeout(t);
+      signal.removeEventListener('abort', done);
+      resolve();
+    }
+    signal.addEventListener('abort', done);
+  });
+}

package/src/commands/flow-init.js

@@ -45,7 +45,7 @@ export async function flowInit(argv, io) {
   io.log(argv.here ? 'npm install' : `cd ${id} && npm install`);
   io.log('npm test');
   io.log('npm run deploy');
-  await printAuthoringIndex('flow', client, target, io);
+  await printAuthoringIndex('flow', client, io);
   return 0;
 }
 

package/src/commands/init.js

@@ -44,7 +44,7 @@ export async function init(argv, io) {
   io.log(argv.here ? 'npm install' : `cd ${id} && npm install`);
   io.log('npm test');
   io.log('npm run deploy');
-  await printAuthoringIndex('integration', client, target, io);
+  await printAuthoringIndex('integration', client, io);
   return 0;
 }
 

package/src/commands/permissions.js

@@ -0,0 +1,47 @@
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+
+export const PERMISSIONS_USAGE =
+  'juno permissions [--allow-change] [--working-copy] [--json]';
+
+/**
+ * `juno permissions` prints a Claude Code permission block on stdout,
+ * `{"permissions":{"allow":[…]}}`: every read command, plus every change
+ * command with --allow-change, plus the working copy's npm scripts of the same
+ * tiers with --working-copy. No act command is ever in it — the server
+ * (GET /api/agent-permissions) leaves them out, and the CLI adds nothing.
+ * Where to put the block goes to stderr, so stdout stays the JSON alone.
+ * `--json` prints the route's body instead.
+ */
+export async function permissions(args, io) {
+  if (args._.length > 0) {
+    throw new UsageError(
+      `juno permissions takes no argument; usage: ${PERMISSIONS_USAGE}`
+    );
+  }
+  const { client } = await connect(args, io);
+  const tiers = await client.getAgentPermissions();
+
+  if (args.json) return printJSON(tiers, io);
+
+  const pick = (t) => [
+    ...(t?.read ?? []),
+    ...(args['allow-change'] ? (t?.change ?? []) : []),
+  ];
+  const allow = pick(tiers);
+  if (args['working-copy']) allow.push(...pick(tiers.working_copy));
+
+  io.warn(
+    args['working-copy']
+      ? "Add these rules to this working copy's .claude/settings.json — not to user-wide settings, " +
+          "where they would also allow any other project's npm scripts:"
+      : 'Add these rules to .claude/settings.json (or ~/.claude/settings.json) to run them without a prompt:'
+  );
+  return printJSON({ permissions: { allow } }, io);
+}
+
+/** Compact off a TTY, indented on one, as every JSON the CLI prints. */
+function printJSON(value, io) {
+  io.log(io.isTTY ? JSON.stringify(value, null, 2) : JSON.stringify(value));
+  return 0;
+}

package/src/commands/run-follow.js

@@ -0,0 +1,68 @@
+import { connect } from '../api.js';
+import { UsageError, UserError } from '../errors.js';
+import { EXIT_INTERRUPTED } from '../exit.js';
+import { runTool } from './tool.js';
+
+/**
+ * `juno run get <run-id> --follow` follows a run as it happens, then prints
+ * what `juno run get` prints. It is a flag on the tool row rather than a row
+ * of its own because the answer is the tool's: the steps stream to stderr as
+ * they finish (`GET /api/flows/{id}/runs/{seq}/trace/stream`, the run page's
+ * live trace), and once the stream says the run is done, get_run's result is
+ * stdout, exactly as without the flag. A run already finished prints at once.
+ * A run waiting on something (an `ask`, a timer) has not finished, so the
+ * follow waits with it; Ctrl-C stops following and leaves the run alone.
+ */
+export async function runFollow(row, args, io) {
+  const [id, ...extra] = args._;
+  if (id === undefined || extra.length) {
+    throw new UsageError(`usage: juno ${row.command} <run-id> --follow`);
+  }
+  const { client } = await connect(args, io);
+  const run = await client.rest(
+    'GET',
+    `/api/runs/${encodeURIComponent(id)}`,
+    undefined,
+    { notFound: `no run ${id}` }
+  );
+  const stream = `/api/flows/${encodeURIComponent(run.flow_id)}/runs/${run.seq}/trace/stream`;
+
+  const interrupt = new AbortController();
+  const off = io.onInterrupt?.(() => interrupt.abort()) ?? (() => {});
+  let done = false;
+  try {
+    for await (const { event, data } of client.events(stream, {
+      signal: interrupt.signal,
+    })) {
+      if (event === 'snapshot') {
+        io.warn(`following ${run.flow_id} run ${run.seq} (${data.status})`);
+        for (const step of data.steps ?? []) io.warn(stepLine(step));
+      } else if (event === 'step') {
+        io.warn(stepLine(data.step ?? {}));
+      } else if (event === 'done') {
+        io.warn(`run ${data.status}${data.error ? `: ${data.error}` : ''}`);
+        done = true;
+        break;
+      }
+    }
+  } finally {
+    off();
+  }
+  if (interrupt.signal.aborted) {
+    io.warn(`stopped following; the run goes on: juno run get ${id}`);
+    return EXIT_INTERRUPTED;
+  }
+  if (!done) {
+    throw new UserError(
+      `the trace stream of run ${id} ended before the run did; read it with: juno run get ${id}`
+    );
+  }
+  return runTool(row, { ...args, follow: undefined }, io);
+}
+
+/** stepLine is one step as a line of progress. */
+function stepLine(step) {
+  const took = step.duration_ms != null ? ` ${step.duration_ms}ms` : '';
+  const err = step.error ? `: ${step.error}` : '';
+  return `  ${step.step_id} ${step.step_type} ${step.status}${took}${err}`;
+}

package/src/commands/session-approve.js

@@ -17,6 +17,10 @@ export const SESSION_APPROVE_USAGE =
  * It checks first that the session is awaiting an approval — anything else
  * sent to a question would be taken as the answer — then sends `approve` as
  * `juno ask` would, and prints and exits the same way.
+ *
+ * A destructive tool's approval (`pending_input.approval_id`) is refused: it
+ * is answered only by a person in Juno, on the page it names, and the server
+ * refuses an `approve` sent to it anyway.
  */
 export async function sessionApprove(args, io) {
   const [id, ...extra] = args._;
@@ -25,10 +29,10 @@ export async function sessionApprove(args, io) {
   }
   const wait = waitSeconds(args.wait);
 
-  const { client } = await connect(args, io);
+  const { client, target } = await connect(args, io);
   const session = await client.getAgentSession(id);
   if (!session) throw new UserError(`no assistant session ${id}`);
-  const refusal = notAwaitingApproval(session, id);
+  const refusal = notAwaitingApproval(session, id, target);
   if (refusal) throw new UserError(refusal);
 
   const body = {
@@ -48,8 +52,11 @@ export async function sessionApprove(args, io) {
 }
 
 /** What the session is doing instead of waiting on an approval, if it is. */
-function notAwaitingApproval(session, id) {
+function notAwaitingApproval(session, id, target) {
   const pending = session.pending_input;
+  if (session.status === 'awaiting_input' && pending?.approval_id) {
+    return `this approval can only be answered in Juno: ${approvalURL(pending, target)}`;
+  }
   if (session.status === 'awaiting_input' && pending?.kind === 'approval') {
     return null;
   }
@@ -71,3 +78,15 @@ function notAwaitingApproval(session, id) {
   }
   return `session ${id} has ended (status: ${session.status}); there is nothing to approve`;
 }
+
+/**
+ * The page an approval is decided on: the server's link, which is a bare path
+ * while the instance has no public URL — completed against the instance this
+ * CLI reached.
+ */
+function approvalURL(pending, target) {
+  const url = pending.approval_url ?? `/approvals/${pending.approval_id}`;
+  return url.startsWith('/')
+    ? `${String(target).replace(/\/+$/, '')}${url}`
+    : url;
+}