@xsft/panels 0.8.1 → 0.10.0

package/README.md

@@ -3,14 +3,17 @@
 `panels run` runs a panel from cross.software/panels against a target. Each judge is a `claude` or `codex` session that scores one criterion of the panel. You need Node 20 or newer and one of the two harnesses.
 
 ```text
+panels login | logout | whoami
+
 panels run <panel> [target...] [flags]
 
-<panel>           owner/name for the latest version, or owner/name@N to pin version N
+<panel>           pnl_SID for latest; pnl_SID@ver_SID or pnl_SID@N to pin a version
+                  owner/name and owner/name@N remain accepted
 [target...]       free words, joined with single spaces into one target
 
 --harness <name>  claude | codex                     default: claude if installed, else codex
 --yolo            the judges skip every permission question (claude --dangerously-skip-permissions, codex --yolo).
-                  Without it, a judge asks its own questions in its tab. Without a terminal, the flag is required.
+                  Without it, a judge asks its own questions in the Agent pane. Without a terminal, the flag is required.
 --                end of the flags; each later word joins the target
 
 exit 0  pass: every criterion scored 4
@@ -18,43 +21,85 @@ exit 1  fail: every judge answered, and one or more criteria scored below 4
 exit 2  error: bad flags, no target, panel not found, harness missing, or a judge failed
 ```
 
-CAUTION: A judge gets no tool block and no sandbox from the CLI. Without `--yolo`, the harness asks its own permission questions in the judge tab. With `--yolo`, nothing asks: the judge can read, write, run commands, and reach the network as you, and the system prompt (do not write or change files of the target, no forms, no posts) is the only guard. Do not run a panel on a repository that you do not trust.
+CAUTION: A judge gets no tool block and no sandbox from the CLI. Without `--yolo`, the harness asks its own permission questions in the Agent pane. With `--yolo`, nothing asks: the judge can read, write, run commands, and reach the network as you, and the system prompt (do not write or change files of the target, no forms, no posts) is the only guard. Do not run a panel on a repository that you do not trust.
 
 ```sh
 npx @xsft/panels run xsft/marketing-site https://example.com --harness claude --yolo
 npx @xsft/panels run xsft/marketing-site@8 . at http://localhost:4321 --harness codex
 ```
 
-Run the command in the folder of the product. Each judge starts in that folder, so `.`, a branch, and relative paths resolve there. The CLI does not test, fetch, or change the target. Four judges run at a time. A judge gets 20 minutes. The criteria of a panel say what to assess; the system prompt of the CLI (`prompts/judge-system-prompt.txt`) carries how to judge and the four levels: 4 Met, 3 Almost met, 2 Falls short, 1 Fails. Only 4 passes.
+Copy the run command from the panel page to use its permanent panel ID. An SID has a type prefix and 32 lowercase hexadecimal digits. A version SID pins one version of that panel. The CLI still accepts `owner/name` and `owner/name@N`.
+
+Run the command in the folder of the product. Plain-mode judges and terminal-mode `claude` start in that folder. Terminal-mode `codex` starts in its judge folder; its prompt names the product folder with an absolute path. The CLI does not test, fetch, or change the target.
+
+Up to ten judges run at a time in terminal mode, or four in plain mode. Terminal mode marks a judge as failed after 20 minutes without an answer. Each plain-mode request gets 20 minutes, including the second request after an invalid answer.
+
+The criteria of a panel say what to assess; the system prompt of the CLI (`prompts/judge-system-prompt.txt`) carries how to judge and the four levels: 4 Met, 3 Almost met, 2 Falls short, 1 Fails. Only 4 passes.
+
+## Account access
+
+Public panels need no login. Team panels require a current team membership. Private panels require the original author's account.
+
+Run `npx -y @xsft/panels@latest login` before you run a team or private panel. Open the URL that the CLI prints. Log in, compare the code with your terminal, then approve the request. The request expires after ten minutes.
+
+`panels whoami` shows the current account. `panels logout` revokes the CLI session and deletes the local token. CLI sessions expire after 30 days. A password change revokes every CLI session and approved login request.
+
+The CLI stores its token in `~/.config/panels/auth.json`, outside the target folder. The file permits access only to its owner. The token applies only to the exact Panels API address. The CLI sends it only to that API and refuses HTTP redirects. It does not copy the token into judge prompts, environment variables, or reports.
 
 ## Terminal mode
 
-On a terminal, `panels run` shows the overview, and each judge runs in its interactive harness in a pseudo-terminal inside the command. Each judge writes `judges/N/answer.json` and stays open. The overview writes the report when each judge has an answer or an error, and the command exits from `report.json` when you quit. Without a terminal, the judges run in the background (`claude -p`, `codex exec`), and stdout prints `N/4  name` and the verdict of each criterion, then the report path. Plain mode needs `--yolo`, because a background judge cannot answer a question; without it the command exits 2.
+On a terminal, `panels run` shows a criterion list and a detail pane. Each judge runs in its interactive harness inside a pseudo-terminal. Each judge writes `judges/N/answer.json` and stays open. The CLI writes the report when every judge has an answer or an error. When you quit, the command exits with the status from `report.json`.
+
+The header shows the panel, target, version, harness, elapsed time, and key hints. At 100 columns or more, the list and detail appear side by side. At smaller widths, the list appears above the detail.
+
+Each list row shows the rank, criterion name, score, elapsed time, and token count. Scores use bright green for 4/4, green for 3/4, yellow for 2/4, and red for 1/4. A pending score shows `·/4`. The total row shows the completed count, scores as quarters, longest judge time, and total tokens.
+
+The detail pane has three tabs:
+
+- **Verdict:** the score and verdict, or an error. Markdown preserves paragraphs and lists, shows bold text and inline code, and indents fenced code blocks.
+- **Agent:** the live session of the selected judge, sized to the pane.
+- **Criterion:** the description and Markdown body of the selected criterion.
+
+Agent is the default while the verdict is pending. Verdict is the default after the judge completes or fails. A manual tab choice stays with the criterion until its pending or completed state changes.
+
+| Focus | Key | Action |
+|---|---|---|
+| List | `↑` / `↓` | Select a criterion |
+| List | `←` / `→` | Select Verdict, Agent, or Criterion |
+| List | `Enter` | Focus the detail pane |
+| Verdict or Criterion | `←` / `→` | Select a tab |
+| Verdict or Criterion | `↑` / `↓` | Scroll one line |
+| Verdict or Criterion | `PgUp` / `PgDn` | Scroll one page |
+| Verdict or Criterion | `Esc` or `Enter` | Return to the list |
+| Agent | `Ctrl-Q` | Return to the list |
+| Agent | Any other key | Send the key to the judge |
+| List | `h` | Choose the harness for the next restart |
+| List | `r` | Confirm a restart of the selected judge |
+| List or text pane | `q` | Quit; press twice if judges still run |
 
-The overview fills the terminal: a header line with the run (panel and target at the left, the version, the harness, and the elapsed time at the right edge) and two columns from 100 columns up (stacked below that). The left column lists the criteria: rank, name, score (4 green, 3 ink, 2 yellow, 1 red, a grey `·/4` until the score arrives), the time the judge has run, and the tokens it used, with a total row at the bottom under a hairline: the scores added as quarters over the number of criteria, the longest judge time, and the tokens added up. The right column shows the criterion under the cursor: its name, score, and level word, then a sub tab bar, `Verdict │ Criterion`, and on the last row the key line. `tab` switches the sub tab: Verdict shows the verdict paragraph, Criterion the description and the body of the criterion as plain text. `enter` moves the focus into the pane (an orange bar marks it): `↑` and `↓` scroll one line, `PgUp` and `PgDn` a page, `esc` or `enter` return to the list. While a judge runs, the Verdict sub tab shows a piece of halftone art in a square frame, generated from a seed per criterion for the run (a half disc, a disc, a ring, a quarter disc, a band, or two discs), breathing, centred in the pane, with the time under it. One soft wave sweeps across the running rows and the art. On the overview, `↑` and `↓` move the cursor. The page never says pass or fail; the total is the result.
+The harness modal offers `claude` and `codex`. The restart modal selects cancel by default. A confirmed restart discards the selected judge's answer and starts that judge with its selected harness. In either modal, `↑` and `↓` select an option, `Enter` confirms it, and `Esc` closes the modal.
 
-`r` opens a small modal that asks before it restarts the judge of the cursor row (the current answer is discarded; `enter` on restart runs it, `esc` cancels). `h` opens a modal that picks the harness of that judge, `claude` or `codex`, for its next restart. While a modal is open, every other key is ignored.
+The first judge starts alone so you can answer a folder trust prompt. With the first criterion and Agent selected, press `Enter` to answer the prompt. Press `Ctrl-Q` to return to the list. The other judges start after the trust prompt clears.
 
-A tab strip on the last three lines shows a hairline, the tabs (`Overview`, then the name of each criterion, split by a grey `│`, cut to the first word when they do not fit), and a status line with the progress, the elapsed time, and the keys. The strip is the navigation area. With the focus on the strip, `←` and `→` move the active tab and switch the view, `1` to `9` jump to a started judge by list order, `0` to the overview, `enter` gives the focus to the judge, and `q` quits; while a judge still runs, the first `q` asks and a second `q` quits. With the focus on a judge, each key goes to the judge, and `ctrl-q` gives the focus back to the strip. The overview takes no text, so the strip keeps the focus there. A harness that has not seen the folder asks whether to trust it. The first judge starts alone; press `1`, answer, and the other judges start.
+Without a terminal, judges run through `claude -p` or `codex exec`. Stdout prints `N/4  name` and each verdict, then the report path. Plain mode requires `--yolo`; without it, the command exits 2.
 
 ## Run folder
 
 Each run writes to `.panels/<owner>-<name>/<UTC time>/`:
 
 - `panel.json`: the panel as the api gave it.
-- `report.json`: `{ panel: "owner/name@version", target, status, criteria: [{ name, score, verdict }] }`, in panel order. `schema/report.json` is its schema, and its `criterion` definition is the shape of the answer of a judge.
+- `report.json`: `{ sid: "run_SID", panel: "pnl_SID@ver_SID", owner, name, version, target, status, criteria: [{ sid, name, score, verdict }] }`, in panel order. The owner, name, and numeric version identify the panel in text output. The run SID stays the same when a judge restarts. Older reports can omit these fields, the run SID, and criterion SIDs. `schema/report.json` is its schema, and its `criterion` definition is the shape of the answer of a judge.
 - `judges/<k>/`: the prompt, the output schema, and the raw answer of judge k. In terminal mode, `answer.json` takes the place of the raw answer.
 
-The last line on stdout is the path of `report.json`.
+In plain mode, the last line on stdout is the path of `report.json`.
 
 ## Skipped
 
 - Run upload to cross.software, and `--no-upload`.
 - `--version`: `owner/name@N` pins a version. The CLI fetches the panel from the api on every run and never caches it.
 - `--out`: the run folder is fixed.
-- `--json`: stdout ends with the path of `report.json`.
-- `--concurrency`: fixed at 4.
+- `--json`: plain-mode stdout ends with the path of `report.json`.
+- `--concurrency`: fixed at ten in terminal mode and four in plain mode.
 - `--model`: each harness uses its default.
 - A panel URL as `<panel>`, a `PANELS_API` override, and a panel cache.
-- A login: an owner cannot run an unpublished panel.
 - Cost totals, and `cap` and `gap` fields.

package/bin/panels.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
+import { randomBytes } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { delimiter, join } from 'node:path';
+import { authCommand } from '../lib/auth.js';
 import { parse, SYNOPSIS } from '../lib/args.js';
 import { runJudge } from '../lib/judge.js';
 import { fetchPanel } from '../lib/panel.js';
@@ -28,8 +30,8 @@ async function pool(items, size, fn) {
 const EXIT = { pass: 0, fail: 1, error: 2 };
 
 /** Runs the judges in the overview, and exits from report.json when the engineer quits. Prints nothing. */
-async function runOnTerminal({ panel, runDir, harness, cwd, args }) {
-  await runTable({ panel, runDir, harness, cwd, target: args.target, yolo: args.yolo });
+async function runOnTerminal({ sid, panel, runDir, harness, cwd, args }) {
+  await runTable({ sid, panel, runDir, harness, cwd, target: args.target, yolo: args.yolo });
   const reportPath = join(runDir, 'report.json');
   if (!existsSync(reportPath)) return 2;
   return EXIT[JSON.parse(readFileSync(reportPath, 'utf8')).status];
@@ -49,6 +51,7 @@ async function main() {
     console.error(`panels: ${args.error}`);
     return 2;
   }
+  if (args.command) return authCommand(args.command);
   const harness = args.harness ?? (onPath('claude') ? 'claude' : 'codex');
   if (!onPath(harness)) {
     console.error(`panels: harness missing: ${harness} is not on PATH`);
@@ -65,12 +68,13 @@ async function main() {
     return 2;
   }
   const { panel } = fetched;
+  const sid = `run_${randomBytes(16).toString('hex')}`;
   const cwd = process.cwd();
   const time = new Date().toISOString().replaceAll(':', '-');
   const runDir = join(cwd, '.panels', `${panel.owner}-${panel.name}`, time);
   mkdirSync(runDir, { recursive: true });
   writeFileSync(join(runDir, 'panel.json'), JSON.stringify(panel, null, 2));
-  if (process.stdout.isTTY && process.stdin.isTTY) return runOnTerminal({ panel, runDir, harness, cwd, args });
+  if (process.stdout.isTTY && process.stdin.isTTY) return runOnTerminal({ sid, panel, runDir, harness, cwd, args });
   const outcomes = await pool(panel.criteria, PARALLEL_JUDGES, (c, i) => runJudge({
     dir: join(runDir, 'judges', String(i + 1)),
     criterion: { rank: i + 1, ...c },
@@ -79,7 +83,7 @@ async function main() {
     target: args.target,
     yolo: true,
   }));
-  const report = buildReport({ panel, target: args.target, outcomes });
+  const report = buildReport({ sid, panel, target: args.target, outcomes });
   const reportPath = join(runDir, 'report.json');
   writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`);
   console.log(renderPlain(report).join('\n'));

package/lib/args.js

@@ -1,8 +1,11 @@
 import { parseArgs } from 'node:util';
 
-export const SYNOPSIS = `panels run <panel> [target...] [flags]
+export const SYNOPSIS = `panels login | logout | whoami
 
-<panel>           owner/name for the latest version, or owner/name@N to pin version N
+panels run <panel> [target...] [flags]
+
+<panel>           pnl_SID for latest; pnl_SID@ver_SID or pnl_SID@N to pin a version
+                  owner/name and owner/name@N remain accepted
 [target...]       free words, joined with single spaces into one target
 
 --harness <name>  claude | codex                     default: claude if installed, else codex
@@ -21,6 +24,7 @@ const options = {
 };
 
 const PANEL = /^([a-z0-9-]+)\/([a-z0-9-]+)(?:@([1-9]\d*))?$/;
+const PANEL_SID = /^(pnl_[a-f0-9]{32})(?:@(ver_[a-f0-9]{32}|[1-9]\d*))?$/;
 
 /** Returns the run options, { help: true }, { usage: true }, or { error } with a one-line message. */
 export function parse(argv) {
@@ -32,13 +36,23 @@ export function parse(argv) {
   }
   if (values.help) return { help: true };
   const [command, panel, ...words] = positionals;
+  if (['login', 'logout', 'whoami'].includes(command)) {
+    if (panel !== undefined || values.harness !== undefined || values.yolo !== undefined) return { usage: true };
+    return { command };
+  }
   if (command !== 'run' || panel === undefined) return { usage: true };
   const match = PANEL.exec(panel);
-  if (!match) return { error: `bad panel ${panel}: use owner/name or owner/name@N` };
+  const sid = PANEL_SID.exec(panel);
+  const version = match?.[3] ?? (sid?.[2]?.startsWith('ver_') ? undefined : sid?.[2]);
+  if ((!match && !sid) || (version !== undefined && !Number.isSafeInteger(Number(version)))) {
+    return { error: `bad panel ${panel}: use pnl_SID[@ver_SID|@N] or owner/name[@N]` };
+  }
   if (words.length === 0) return { error: 'no target: type what the panel reviews after the panel name, such as a URL, a path, or a branch' };
   if (values.harness !== undefined && !['claude', 'codex'].includes(values.harness)) return { error: `--harness needs claude or codex, not ${values.harness}` };
   return {
-    panel: { owner: match[1], name: match[2], version: match[3] && Number(match[3]) },
+    panel: sid
+      ? { sid: sid[1], ...(sid[2]?.startsWith('ver_') ? { versionSid: sid[2] } : { version: version && Number(version) }) }
+      : { owner: match[1], name: match[2], version: version && Number(version) },
     target: words.join(' '),
     harness: values.harness,
     yolo: Boolean(values.yolo),

package/lib/auth.js

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+
+export const API = 'https://cross.software/panels/api';
+const credentials = () => join(homedir(), '.config', 'panels', 'auth.json');
+
+export async function readToken(api = API, file = credentials()) {
+  const value = await readFile(file, 'utf8').then(JSON.parse, (error) => {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  });
+  return value?.api === api ? value.token : undefined;
+}
+
+export async function saveToken(token, api = API, file = credentials()) {
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+  await chmod(dirname(file), 0o700);
+  const temporary = `${file}.${randomUUID()}`;
+  await writeFile(temporary, `${JSON.stringify({ api, token })}\n`, { mode: 0o600, flag: 'wx' });
+  await rename(temporary, file);
+}
+
+export async function authFetch(path, { api = API, token, ...init } = {}) {
+  return fetch(`${api}${path}`, {
+    ...init,
+    redirect: 'error',
+    cache: 'no-store',
+    headers: { ...init.headers, ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+  });
+}
+
+export async function authCommand(command, { api = API, file = credentials(), log = console.log, wait = setTimeout } = {}) {
+  if (command === 'login') {
+    const response = await authFetch('/cli/device', { api, method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' });
+    if (!response.ok) throw new Error(`login failed: ${response.status}`);
+    const device = await response.json();
+    log(`Open ${device.verificationUri}`);
+    log(`Check code ${device.userCode}, then approve the login. This request expires in 10 minutes.`);
+    const expiresAt = Date.now() + device.expiresIn * 1000;
+    while (Date.now() < expiresAt) {
+      await wait(device.interval * 1000);
+      const answer = await authFetch('/cli/token', {
+        api, method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ deviceCode: device.deviceCode }),
+      });
+      if (answer.status === 202) continue;
+      if (!answer.ok) throw new Error('login expired or failed; run panels login again');
+      const { token, user } = await answer.json();
+      await saveToken(token, api, file);
+      log(`Logged in as ${user.handle}.`);
+      return 0;
+    }
+    throw new Error('login expired; run panels login again');
+  }
+  const token = await readToken(api, file);
+  if (!token) {
+    log('Not logged in. Run panels login.');
+    return command === 'logout' ? 0 : 2;
+  }
+  if (command === 'logout') {
+    const response = await authFetch('/cli/session', { api, token, method: 'DELETE', headers: { 'Content-Type': 'application/json' } });
+    if (!response.ok && response.status !== 401) throw new Error(`logout failed: ${response.status}`);
+    await rm(file, { force: true });
+    log('Logged out.');
+    return 0;
+  }
+  const response = await authFetch('/viewer', { api, token });
+  if (!response.ok) throw new Error(`account fetch failed: ${response.status}`);
+  const user = await response.json();
+  log(user ? `${user.handle} (${user.email})` : 'Login expired. Run panels login.');
+  return user ? 0 : 2;
+}

package/lib/judge.js

@@ -4,6 +4,16 @@ import { join } from 'node:path';
 
 const { criterion: CRITERION } = JSON.parse(readFileSync(new URL('../schema/report.json', import.meta.url), 'utf8')).$defs;
 const SYSTEM_PROMPT = readFileSync(new URL('../prompts/judge-system-prompt.txt', import.meta.url), 'utf8');
+/** The words of Navid to every judge of the terminal mode, as he wrote them on 2026-10-18. */
+export const GUIDANCE = `You give a score from 1 to 4 and a verdict. Anyone may read it. Write so they understand it the first time and know what to do next.
+
+A problem is useful only if someone can fix it. "This feels weak" cannot be fixed. "The page never says what goes wrong without the product" can. So say what is missing, where it should be, and show the words that are there now.
+
+Find the problems first. Then score. 4 means you would put this site live today. Only 4 is a pass. The closer a problem is to what the visitor sees first, the lower the score.
+
+Keep it short. A long paragraph that shows you looked at everything hides the reason for the score. If you skipped something, write "Not checked:" and name it. That is enough.
+
+You will want to write down everything you saw, good parts first. Do not. Write what is missing.`;
 export const MINUTES_PER_CRITERION = 20;
 // A judge gets no tool list, no permission mode, and no sandbox flag: the harness defaults, and its own questions
 // in its tab. With --yolo, the judge skips every question: no sandbox, nothing is denied, nothing asks. The system
@@ -35,7 +45,7 @@ export function check(answer, criterion) {
   const errors = [];
   if (answer.name !== criterion.name) errors.push(`name must be "${criterion.name}".`);
   if (!Number.isInteger(answer.score) || answer.score < 1 || answer.score > 4) errors.push('score must be a whole number from 1 to 4.');
-  if (typeof answer.verdict !== 'string' || !answer.verdict.trim()) errors.push('verdict must be one paragraph of text.');
+  if (typeof answer.verdict !== 'string' || !answer.verdict.trim()) errors.push('verdict must be text.');
   return errors;
 }
 
@@ -130,9 +140,9 @@ export const tomlString = (s) => `"${s.replace(/["\\\x00-\x1f\x7f]/g, (c) => TOM
  */
 export function writeJudge({ dir, criterion, harness, cwd, target, yolo = false }) {
   mkdirSync(dir, { recursive: true });
-  // The answer file rule sits at the end of the user prompt and in the system prompt, so a judge that hands the
-  // work to a sub-agent still leaves the file at the exact path.
-  const closing = `The engineer ran the command in ${cwd}. Your answer counts only as the file ${join(dir, 'answer.json')}: write it with that exact absolute path, as one JSON object { name, score, verdict } that matches ${join(dir, 'schema.json')}. JSON in your reply does not count. Whoever does the work, that file must exist at that path when you stop. These two files are the only exceptions to the rules on writing files and on the .panels folder.\n`;
+  // Navid's words to the judge (2026-10-18), verbatim, then the answer file rule. Both sit at the end of the user
+  // prompt and in the system prompt, so a judge that hands the work to a sub-agent still leaves the file at the exact path.
+  const closing = `${GUIDANCE}\n\nThe engineer ran the command in ${cwd}. Your answer counts only as the file ${join(dir, 'answer.json')}: write it with that exact absolute path, as one JSON object { name, score, verdict } that matches ${join(dir, 'schema.json')}. JSON in your reply does not count. Whoever does the work, that file must exist at that path when you stop. These two files are the only exceptions to the rules on writing files and on the .panels folder.\n`;
   const prompt = `${userMessage(criterion, { target })}\n${closing}`;
   const system = `${SYSTEM_PROMPT}\n${closing}`;
   writeFileSync(join(dir, 'prompt.md'), prompt);

package/lib/panel.js

@@ -1,13 +1,14 @@
-const API = 'https://cross.software/panels/api/panels';
+import { API, authFetch, readToken } from './auth.js';
 
-/**
- * Reads a panel from the public api on every run, the latest version unless one is pinned, and never from a
- * cache: the api answers no-store, and the fetch asks for no store too, so a proxy cannot keep a copy.
- * An unpublished panel also answers 404.
- */
-export async function fetchPanel({ owner, name, version }) {
-  const res = await fetch(`${API}/${owner}/${name}${version ? `/v/${version}` : ''}`, { cache: 'no-store' });
-  if (res.status === 404) return { error: 'panel not found' };
+/** Reads the current panel or a pinned version. The API checks the account on every request. */
+export async function fetchPanel({ owner, name, sid, version, versionSid }, { api = API, file } = {}) {
+  const token = await readToken(api, file);
+  const reference = sid ?? `${owner}/${name}`;
+  const pin = versionSid ? `/versions/${versionSid}` : version ? `/v/${version}` : '';
+  const res = await authFetch(`/panels/${reference}${pin}`, { api, token });
+  if (res.status === 401) return { error: 'login required: run panels login' };
+  if (res.status === 403) return { error: 'this account cannot access the panel' };
+  if (res.status === 404) return { error: token ? 'panel not found or this account has no access' : 'panel not found; for a team or private panel, run panels login' };
   if (!res.ok) return { error: `panel fetch failed: ${res.status}` };
   return { panel: await res.json() };
 }

package/lib/report.js

@@ -4,18 +4,20 @@ import { readFileSync } from 'node:fs';
 export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 
 /**
- * Builds report.json: { panel: "owner/name@version", target, status, criteria }. outcomes holds the
- * { answer } or { error } of the judge of each criterion, in panel order. A criterion whose judge failed
- * gets score null and the error as its verdict, and the run status is error. The panel passes only when
- * every criterion scores 4.
+ * Each outcome belongs to the criterion at the same index in panel.criteria.
+ * A failed judge gives score null and status error. Every criterion must score 4 for a pass.
  */
-export function buildReport({ panel, target, outcomes }) {
+export function buildReport({ sid, panel, target, outcomes }) {
   const criteria = panel.criteria.map((c, i) => {
     const { answer, error } = outcomes[i];
-    return answer ? { name: c.name, score: answer.score, verdict: answer.verdict } : { name: c.name, score: null, verdict: `error: ${error}` };
+    return { ...(c.sid ? { sid: c.sid } : {}), name: c.name, score: answer ? answer.score : null, verdict: answer ? answer.verdict : `error: ${error}` };
   });
   const status = criteria.some((c) => c.score === null) ? 'error' : criteria.every((c) => c.score === 4) ? 'pass' : 'fail';
-  return { panel: `${panel.owner}/${panel.name}@${panel.version}`, target, status, criteria };
+  return {
+    sid,
+    panel: panel.sid ? `${panel.sid}@${panel.versionSid}` : `${panel.owner}/${panel.name}@${panel.version}`,
+    owner: panel.owner, name: panel.name, version: panel.version, target, status, criteria,
+  };
 }
 
 /**
@@ -23,6 +25,8 @@ export function buildReport({ panel, target, outcomes }) {
  * "N/4  name" and the verdict under it, for each criterion.
  */
 export function renderPlain(report) {
-  const [name, version] = report.panel.split('@');
+  const [reference, pin] = report.panel.split('@');
+  const name = report.owner ? `${report.owner}/${report.name}` : reference;
+  const version = report.version ?? pin;
   return [`panels run  ${name} v${version}   ${report.target}   ${VERSION}`, '', ...report.criteria.flatMap((c) => [`${c.score === null ? 'err' : `${c.score}/4`}  ${c.name}`, `    ${c.verdict}`, ''])];
 }