@akagilnc/pi-workflow-roles 0.1.1941 → 0.1.2014

package/src/ledger-session-read.ts

@@ -0,0 +1,260 @@
+/**
+ * Canonical ledger session JSONL read primitives (shared owner).
+ * Consumers (ticket-trajectory, taishi, …) must import here — no second parse kernel.
+ */
+import { readFile } from "node:fs/promises";
+
+export type LedgerSessionRow = Record<string, unknown>;
+
+/**
+ * Loud JSONL failure that still retains rows parsed before the bad line.
+ * Callers that only need the throw keep catching Error; owners that must
+ * surface partial typed facts (e.g. first-frame timestamp) read prefixRows.
+ */
+export class LedgerSessionJsonlError extends Error {
+  readonly path: string;
+  readonly line: number;
+  readonly prefixRows: readonly LedgerSessionRow[];
+
+  constructor(
+    message: string,
+    init: {
+      readonly path: string;
+      readonly line: number;
+      readonly prefixRows: readonly LedgerSessionRow[];
+    },
+  ) {
+    super(message);
+    this.name = "LedgerSessionJsonlError";
+    this.path = init.path;
+    this.line = init.line;
+    this.prefixRows = init.prefixRows;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read session JSONL with honest live-tail semantics:
+ * a malformed line is tolerated only when it is an unfinished final
+ * fragment at EOF (no record terminator after it). Any malformed line
+ * completed by a line terminator must fail loudly with file and 1-based
+ * line context — even when no non-empty record follows — never silently
+ * under-count.
+ *
+ * Loud failures throw LedgerSessionJsonlError carrying prefixRows so the
+ * single parse kernel can still expose facts obtained before the bad line.
+ */
+export async function readLedgerSessionJsonl(path: string): Promise<LedgerSessionRow[]> {
+  const text = await readFile(path, "utf8");
+  // split keeps a trailing empty segment iff text ends with "\n", so
+  // index < lines.length - 1 means this segment was terminated.
+  const lines = text.split("\n");
+  const rows: LedgerSessionRow[] = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    if (!line.trim()) continue;
+    let row: unknown;
+    try {
+      row = JSON.parse(line);
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw error;
+      const completedByTerminator = index < lines.length - 1;
+      if (completedByTerminator) {
+        throw new LedgerSessionJsonlError(
+          `malformed JSONL record in ${path} at line ${index + 1}: ${error.message}`,
+          { path, line: index + 1, prefixRows: rows },
+        );
+      }
+      // unfinished fragment at EOF — keep prior complete rows
+      break;
+    }
+    // Syntactically complete line: must be a session object. Silent omission
+    // would under-count ledger evidence (failure honesty).
+    if (!isRecord(row)) {
+      const kind = row === null ? "null" : Array.isArray(row) ? "array" : typeof row;
+      throw new LedgerSessionJsonlError(
+        `complete non-object JSONL record in ${path} at line ${index + 1}: expected object, got ${kind}`,
+        { path, line: index + 1, prefixRows: rows },
+      );
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+
+/** First and last record timestamps in encounter order. */
+export function extractSessionTimestampSpan(
+  rows: readonly LedgerSessionRow[],
+): { startedAt?: string; endedAt?: string } {
+  let startedAt: string | undefined;
+  let endedAt: string | undefined;
+  for (const row of rows) {
+    if (typeof row.timestamp !== "string" || !row.timestamp) continue;
+    if (startedAt === undefined) startedAt = row.timestamp;
+    endedAt = row.timestamp;
+  }
+  return {
+    ...(startedAt !== undefined ? { startedAt } : {}),
+    ...(endedAt !== undefined ? { endedAt } : {}),
+  };
+}
+
+/**
+ * Ordered-unique model ids from session frames (first-seen order).
+ * Sources (same faces ticket-trajectory already reads — single parse kernel):
+ * - `model_change.modelId`
+ * - assistant `message.model`
+ * Blank / non-string values are skipped. Does not invent a default model.
+ */
+export function extractSessionModelSequence(
+  rows: readonly LedgerSessionRow[],
+): string[] {
+  const seen = new Set<string>();
+  const ordered: string[] = [];
+  const push = (raw: string): void => {
+    const model = raw.trim();
+    if (model === "" || seen.has(model)) return;
+    seen.add(model);
+    ordered.push(model);
+  };
+  for (const row of rows) {
+    if (row.type === "model_change" && typeof row.modelId === "string") {
+      push(row.modelId);
+    }
+    const message = isRecord(row.message) ? row.message : undefined;
+    if (message?.role === "assistant" && typeof message.model === "string") {
+      push(message.model);
+    }
+  }
+  return ordered;
+}
+
+/** First line of a bash `command` argument (sole owner of this summary). */
+export function bashCommandFirstLine(command: string): string {
+  const match = /^[^\r\n]*/.exec(command);
+  return match?.[0] ?? "";
+}
+
+export type SessionToolInterval = {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly startedAt: string;
+  readonly endedAt?: string;
+  /**
+   * Bash-only first-line command summary from `arguments.command`.
+   * Omitted for non-bash tools and when the argument is absent/non-string.
+   * Full multi-line bodies are never retained on this typed fact face.
+   */
+  readonly command?: string;
+};
+
+/**
+ * Pair toolCall frames → toolResult frames by toolCallId.
+ * Throws when a tool-bearing frame is structurally unreadable for association
+ * (toolCall missing string id, toolResult missing string toolCallId).
+ * Unpaired open calls remain without endedAt — that is incomplete, not unreadable.
+ */
+export function extractSessionToolIntervals(
+  rows: readonly LedgerSessionRow[],
+): SessionToolInterval[] {
+  type Open = {
+    toolCallId: string;
+    toolName: string;
+    startedAt: string;
+    endedAt?: string;
+    command?: string;
+  };
+  const order: Open[] = [];
+  const openById = new Map<string, Open>();
+
+  for (const row of rows) {
+    const rowTimestamp = typeof row.timestamp === "string" ? row.timestamp : undefined;
+    const message = isRecord(row.message) ? row.message : undefined;
+
+    if (message?.role === "assistant" && Array.isArray(message.content)) {
+      const callTimestamp =
+        typeof message.timestamp === "string" && message.timestamp
+          ? message.timestamp
+          : rowTimestamp;
+      for (const part of message.content) {
+        if (!isRecord(part) || part.type !== "toolCall") continue;
+        if (typeof part.id !== "string" || part.id.length === 0) {
+          throw new Error("toolCall frame missing string id");
+        }
+        if (typeof part.name !== "string" || part.name.length === 0) {
+          throw new Error(`toolCall ${part.id} missing string name`);
+        }
+        if (callTimestamp === undefined || callTimestamp.length === 0) {
+          throw new Error(`toolCall ${part.id} missing timestamp`);
+        }
+        if (openById.has(part.id)) {
+          throw new Error(`duplicate toolCall id ${part.id}`);
+        }
+        const args = isRecord(part.arguments) ? part.arguments : undefined;
+        // Ticket surface: only bash first-line summary is authorized here.
+        const command =
+          part.name === "bash" &&
+          args !== undefined &&
+          typeof args.command === "string"
+            ? bashCommandFirstLine(args.command)
+            : undefined;
+        const interval: Open = {
+          toolCallId: part.id,
+          toolName: part.name,
+          startedAt: callTimestamp,
+          ...(command !== undefined ? { command } : {}),
+        };
+        order.push(interval);
+        openById.set(part.id, interval);
+      }
+    }
+
+    if (message?.role === "toolResult") {
+      if (typeof message.toolCallId !== "string" || message.toolCallId.length === 0) {
+        throw new Error("toolResult frame missing string toolCallId");
+      }
+      const resultTimestamp =
+        typeof message.timestamp === "string" && message.timestamp
+          ? message.timestamp
+          : rowTimestamp;
+      if (resultTimestamp === undefined || resultTimestamp.length === 0) {
+        throw new Error(`toolResult ${message.toolCallId} missing timestamp`);
+      }
+      const open = openById.get(message.toolCallId);
+      if (open === undefined) {
+        // Result without a prior call is still associable as a closed interval
+        // once a name is known; keep structural readability without inventing a call.
+        const toolName =
+          typeof message.toolName === "string" && message.toolName.length > 0
+            ? message.toolName
+            : "unknown";
+        order.push({
+          toolCallId: message.toolCallId,
+          toolName,
+          startedAt: resultTimestamp,
+          endedAt: resultTimestamp,
+        });
+        continue;
+      }
+      if (open.endedAt !== undefined) {
+        throw new Error(`duplicate toolResult for toolCallId ${message.toolCallId}`);
+      }
+      open.endedAt = resultTimestamp;
+    }
+  }
+
+  return order.map((interval) => {
+    const base = {
+      toolCallId: interval.toolCallId,
+      toolName: interval.toolName,
+      startedAt: interval.startedAt,
+      ...(interval.command !== undefined ? { command: interval.command } : {}),
+    };
+    return interval.endedAt === undefined
+      ? base
+      : { ...base, endedAt: interval.endedAt };
+  });
+}

package/src/package-contracts/reviewer-output.ts

@@ -35,6 +35,8 @@ export type RuntimeReviewerReceiptV2 = Readonly<{
   acceptedBatch?: RuntimeReviewerAcceptedBatch;
   /** Present on accepted batches: launched Spec child, or skipped after confirmed missing Spec. */
   specDisposition?: RuntimeReviewerSpecDisposition;
+  /** Self-fetch bytes + source annotation when Spec primary path produced material (#343). */
+  specFetchedMaterial?: ReviewerAcceptedEvidence["specFetchedMaterial"];
   reports: Readonly<Partial<Record<"standards" | "spec", VerbatimChildReport>>>;
   outcomes: Readonly<Partial<Record<"standards" | "spec", RuntimeReviewerOutcome>>>;
   identities: Readonly<{

package/src/public-cli/cli.ts

@@ -32,6 +32,7 @@ import {
   parseJudgeArgv,
   parseMergerArgv,
   parseReviewerArgv,
+  parseTaishiArgv,
 } from "./invocation.ts";
 import { runPublicCoder, runPublicCoderResume } from "./coder-run.ts";
 import { runPublicCollector } from "./collector-run.ts";
@@ -40,6 +41,7 @@ import { runPublicFixer, runPublicFixerResume } from "./fixer-run.ts";
 import { runPublicJudge, runPublicResume } from "./judge-run.ts";
 import { runPublicMerger, runPublicMergerResume } from "./merger-run.ts";
 import { runPublicReviewer, runPublicReviewerResume } from "./reviewer-run.ts";
+import { runPublicTaishi } from "./taishi-run.ts";
 import { peekRoleRunRole } from "./run-lifecycle.ts";
 import {
   INTERNAL_ROLE_ENTRYPOINT_RELATIVE,
@@ -73,6 +75,8 @@ export const PUBLIC_ROLE_ARGV = {
   doctor: { parse: parseDoctorArgv },
   merger: { parse: parseMergerArgv },
   reviewer: { parse: parseReviewerArgv },
+  /** Deterministic analysis seat (#336) — argv parse only; no LLM admission. */
+  taishi: { parse: parseTaishiArgv },
 } as const;
 
 type TakenPublicGlobalFlag =
@@ -314,6 +318,12 @@ function renderHelp(): string {
       lines.push(`  ${cap.name} — ${phaseText}`);
     }
   }
+  lines.push("", "Deterministic commands:");
+  for (const cap of doc.capabilities) {
+    if (cap.kind === "deterministic") {
+      lines.push(`  ${cap.name}`);
+    }
+  }
   lines.push(
     "",
     "Global options: --model provider/model --thinking level",
@@ -430,6 +440,8 @@ export async function runAkRole(
         }
         if (match.kind === "support") {
           io.stdout(`command\t${match.name}\tkind\tsupport\n`);
+        } else if (match.kind === "deterministic") {
+          io.stdout(`command\t${match.name}\tkind\tdeterministic\n`);
         } else {
           io.stdout(
             `command\t${match.name}\tkind\trole\tphases\t${match.phases
@@ -949,6 +961,18 @@ export async function runAkRole(
       };
     }
 
+    // Taishi public run path: deterministic analysis seat (#336 issue / #337 sweep).
+    // Not an LLM PUBLIC_CALLABLE_ROLE — registered only on PUBLIC_ROLE_ARGV (#176).
+    if (parsed.command === "taishi") {
+      const result = await runPublicTaishi(
+        parsed.args,
+        { home },
+        io,
+        PUBLIC_ROLE_ARGV.taishi.parse,
+      );
+      return { exitCode: result.exitCode };
+    }
+
     // #115: every PUBLIC_CALLABLE_ROLE has a completed handler above. Unknown
     // tokens (including misspelled role names) are structural rejects.
     throw new CliUsageError(`unknown command: ${parsed.command}`);

package/src/public-cli/invocation.ts

@@ -334,6 +334,50 @@ export type ParseMergerArgvResult = {
   project?: string;
 };
 
+/**
+ * #336/#337/#338 taishi public argv — four faces on one registration seam.
+ * - issue (default): ticket N and/or project-root P
+ * - sweep (#337): optional positional `sweep` and/or --attach paths;
+ *   sweep payload rides exactly one typed JSON attachment (not argv/stdin)
+ * - cohort: two labeled issue-number groups
+ * - model-groups: one or more project-root scope keys
+ */
+export type ParseTaishiIssueArgv = {
+  readonly query: "issue";
+  /** Caller ticket / issue number face (#176 numbering space). */
+  readonly ticket?: number;
+  /** Direct projectRoot mechanical key (ADR 0068). */
+  readonly projectRoot?: string;
+};
+
+export type ParseTaishiSweepArgv = {
+  readonly query: "sweep";
+  /**
+   * Public CLI attachment paths (--attach). Sweep mode only (#337).
+   * Cardinality validated on the sweep run path (exactly one).
+   */
+  readonly attachmentPaths: readonly string[];
+};
+
+export type ParseTaishiCohortArgv = {
+  readonly query: "cohort";
+  readonly groups: readonly [
+    { readonly groupLabel: string; readonly issues: readonly number[] },
+    { readonly groupLabel: string; readonly issues: readonly number[] },
+  ];
+};
+
+export type ParseTaishiModelGroupsArgv = {
+  readonly query: "model-groups";
+  readonly projectRoots: readonly string[];
+};
+
+export type ParseTaishiArgvResult =
+  | ParseTaishiIssueArgv
+  | ParseTaishiSweepArgv
+  | ParseTaishiCohortArgv
+  | ParseTaishiModelGroupsArgv;
+
 /** Honest activation-class failure while deriving the active-merge envelope. */
 export class MergerEnvelopeDerivationError extends Error {
   readonly code = "merger-envelope-derivation" as const;
@@ -347,7 +391,13 @@ export class MergerEnvelopeDerivationError extends Error {
 
 /** Reject missing/blank path values so empty overrides cannot silently degrade. */
 function requireOptionPath(
-  flag: "--project" | "--attach" | "--prerequisites" | "--request-manifest" | "--base",
+  flag:
+    | "--project"
+    | "--attach"
+    | "--prerequisites"
+    | "--request-manifest"
+    | "--base"
+    | "--project-root",
   value: string | undefined,
 ): string {
   if (value === undefined || value.trim() === "") {
@@ -2041,3 +2091,304 @@ export function buildMergerTransportPrompt(
   }
   return lines.join("\n");
 }
+
+const TAISHI_TICKET_NUMBER_PATTERN = /^[1-9]\d*$/;
+
+/**
+ * Parse a positive ticket / issue number for public taishi admission.
+ * Leading zeros and non-integers are structural rejects (same face as #176).
+ * `flag` names the actual argv face in diagnostics (cohort group lists reuse this).
+ */
+export function parseTaishiTicketNumber(
+  raw: string,
+  flag: string = "--ticket",
+): number {
+  const trimmed = raw.trim();
+  if (!TAISHI_TICKET_NUMBER_PATTERN.test(trimmed)) {
+    throw new CliUsageError(
+      `taishi ${flag} must be a positive integer, got ${raw}`,
+    );
+  }
+  const value = Number(trimmed);
+  // Digit-only strings beyond MAX_SAFE_INTEGER round or become Infinity — reject.
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new CliUsageError(
+      `taishi ${flag} must be a positive integer, got ${raw}`,
+    );
+  }
+  return value;
+}
+
+function parseTaishiIssueNumberList(raw: string, flag: string): number[] {
+  const trimmed = raw.trim();
+  if (trimmed === "") {
+    throw new CliUsageError(`${flag} requires a comma-separated positive integer list`);
+  }
+  const parts = trimmed.split(",").map((part) => part.trim());
+  if (parts.some((part) => part === "")) {
+    throw new CliUsageError(`${flag} requires a comma-separated positive integer list`);
+  }
+  // Same numeric rule as --ticket; diagnostic names the actual group flag.
+  return parts.map((part) => parseTaishiTicketNumber(part, flag));
+}
+
+function requireOptionValue(
+  flag: string,
+  value: string | undefined,
+  what: string,
+): string {
+  if (value === undefined || value.trim() === "") {
+    throw new CliUsageError(`${flag} requires ${what}`);
+  }
+  return value;
+}
+
+/**
+ * Parse taishi-specific argv after the `taishi` token (#336/#337/#338).
+ * Issue: at least one of --ticket / --project-root.
+ * Sweep: positional `sweep` and/or --attach; payload is the attachment body only.
+ * Cohort / model-groups: explicit query flags with their own required faces.
+ * Faces are mutually exclusive.
+ */
+export function parseTaishiArgv(args: readonly string[]): ParseTaishiArgvResult {
+  let query: "issue" | "cohort" | "model-groups" = "issue";
+  let ticketRaw: string | undefined;
+  const projectRoots: string[] = [];
+  let groupALabel: string | undefined;
+  let groupAIssuesRaw: string | undefined;
+  let groupBLabel: string | undefined;
+  let groupBIssuesRaw: string | undefined;
+  let sweepToken = false;
+  const attachmentPaths: string[] = [];
+  const tokens = [...args];
+
+  while (tokens.length > 0) {
+    const token = tokens.shift()!;
+    if (token === "--") {
+      if (tokens.length > 0) {
+        throw new CliUsageError(`unexpected taishi argument: ${tokens[0]}`);
+      }
+      break;
+    }
+    if (token === "--cohort") {
+      if (query !== "issue") {
+        throw new CliUsageError("taishi accepts only one of --cohort / --model-groups");
+      }
+      query = "cohort";
+      continue;
+    }
+    if (token === "--model-groups") {
+      if (query !== "issue") {
+        throw new CliUsageError("taishi accepts only one of --cohort / --model-groups");
+      }
+      query = "model-groups";
+      continue;
+    }
+    if (token === "--ticket") {
+      const value = tokens.shift();
+      if (value === undefined || value.trim() === "") {
+        throw new CliUsageError("taishi --ticket requires a positive integer");
+      }
+      ticketRaw = value;
+      continue;
+    }
+    if (token.startsWith("--ticket=")) {
+      ticketRaw = token.slice("--ticket=".length);
+      if (ticketRaw.trim() === "") {
+        throw new CliUsageError("taishi --ticket requires a positive integer");
+      }
+      continue;
+    }
+    if (token === "--project-root") {
+      projectRoots.push(requireOptionPath("--project-root", tokens.shift()));
+      continue;
+    }
+    if (token.startsWith("--project-root=")) {
+      projectRoots.push(
+        requireOptionPath("--project-root", token.slice("--project-root=".length)),
+      );
+      continue;
+    }
+    if (token === "--group-a-label") {
+      groupALabel = requireOptionValue("--group-a-label", tokens.shift(), "a label");
+      continue;
+    }
+    if (token.startsWith("--group-a-label=")) {
+      groupALabel = requireOptionValue(
+        "--group-a-label",
+        token.slice("--group-a-label=".length),
+        "a label",
+      );
+      continue;
+    }
+    if (token === "--group-a-issues") {
+      groupAIssuesRaw = requireOptionValue(
+        "--group-a-issues",
+        tokens.shift(),
+        "a comma-separated positive integer list",
+      );
+      continue;
+    }
+    if (token.startsWith("--group-a-issues=")) {
+      groupAIssuesRaw = requireOptionValue(
+        "--group-a-issues",
+        token.slice("--group-a-issues=".length),
+        "a comma-separated positive integer list",
+      );
+      continue;
+    }
+    if (token === "--group-b-label") {
+      groupBLabel = requireOptionValue("--group-b-label", tokens.shift(), "a label");
+      continue;
+    }
+    if (token.startsWith("--group-b-label=")) {
+      groupBLabel = requireOptionValue(
+        "--group-b-label",
+        token.slice("--group-b-label=".length),
+        "a label",
+      );
+      continue;
+    }
+    if (token === "--group-b-issues") {
+      groupBIssuesRaw = requireOptionValue(
+        "--group-b-issues",
+        tokens.shift(),
+        "a comma-separated positive integer list",
+      );
+      continue;
+    }
+    if (token.startsWith("--group-b-issues=")) {
+      groupBIssuesRaw = requireOptionValue(
+        "--group-b-issues",
+        token.slice("--group-b-issues=".length),
+        "a comma-separated positive integer list",
+      );
+      continue;
+    }
+    if (token === "--attach") {
+      attachmentPaths.push(requireOptionPath("--attach", tokens.shift()));
+      continue;
+    }
+    if (token.startsWith("--attach=")) {
+      attachmentPaths.push(
+        requireOptionPath("--attach", token.slice("--attach=".length)),
+      );
+      continue;
+    }
+    if (token.startsWith("-") && token !== "-") {
+      throw new CliUsageError(`unknown taishi option: ${token}`);
+    }
+    // Optional sweep mode token (like coder plan/apply); only once, no other positionals.
+    if (token === "sweep") {
+      if (sweepToken) {
+        throw new CliUsageError("unexpected taishi argument: sweep");
+      }
+      sweepToken = true;
+      continue;
+    }
+    throw new CliUsageError(`unexpected taishi argument: ${token}`);
+  }
+
+  const hasSweepFace = sweepToken || attachmentPaths.length > 0;
+  const hasCohortFlags =
+    groupALabel !== undefined
+    || groupAIssuesRaw !== undefined
+    || groupBLabel !== undefined
+    || groupBIssuesRaw !== undefined;
+
+  if (query === "cohort") {
+    if (
+      groupALabel === undefined
+      || groupAIssuesRaw === undefined
+      || groupBLabel === undefined
+      || groupBIssuesRaw === undefined
+    ) {
+      throw new CliUsageError(
+        "usage: ak-role taishi --cohort --group-a-label <L> --group-a-issues <N[,N...]> --group-b-label <L> --group-b-issues <N[,N...]>",
+      );
+    }
+    if (ticketRaw !== undefined || projectRoots.length > 0) {
+      throw new CliUsageError(
+        "taishi --cohort does not accept --ticket or --project-root",
+      );
+    }
+    if (hasSweepFace) {
+      throw new CliUsageError(
+        "taishi --cohort does not accept sweep --attach",
+      );
+    }
+    return {
+      query: "cohort",
+      groups: [
+        {
+          groupLabel: groupALabel,
+          issues: parseTaishiIssueNumberList(groupAIssuesRaw, "--group-a-issues"),
+        },
+        {
+          groupLabel: groupBLabel,
+          issues: parseTaishiIssueNumberList(groupBIssuesRaw, "--group-b-issues"),
+        },
+      ],
+    };
+  }
+
+  if (query === "model-groups") {
+    if (projectRoots.length === 0) {
+      throw new CliUsageError(
+        "usage: ak-role taishi --model-groups --project-root <P> [--project-root <P> ...]",
+      );
+    }
+    if (ticketRaw !== undefined) {
+      throw new CliUsageError("taishi --model-groups does not accept --ticket");
+    }
+    if (hasCohortFlags) {
+      throw new CliUsageError("taishi --model-groups does not accept cohort group flags");
+    }
+    if (hasSweepFace) {
+      throw new CliUsageError(
+        "taishi --model-groups does not accept sweep --attach",
+      );
+    }
+    return {
+      query: "model-groups",
+      projectRoots,
+    };
+  }
+
+  // default issue or sweep (#336/#337 faces)
+  if (hasCohortFlags) {
+    throw new CliUsageError("taishi issue query does not accept cohort group flags");
+  }
+
+  if (hasSweepFace) {
+    if (ticketRaw !== undefined || projectRoots.length > 0) {
+      throw new CliUsageError(
+        "taishi sweep --attach cannot combine with --ticket or --project-root",
+      );
+    }
+    return {
+      query: "sweep",
+      attachmentPaths,
+    };
+  }
+
+  if (projectRoots.length > 1) {
+    throw new CliUsageError(
+      "taishi issue query accepts at most one --project-root (use --model-groups for many)",
+    );
+  }
+  const projectRoot = projectRoots[0];
+  if (ticketRaw === undefined && projectRoot === undefined) {
+    throw new CliUsageError(
+      "usage: ak-role taishi ((--ticket <N> | --project-root <P>) | [sweep] --attach <sweep.json> | --cohort ... | --model-groups ...)",
+    );
+  }
+
+  return {
+    query: "issue",
+    ...(ticketRaw === undefined
+      ? {}
+      : { ticket: parseTaishiTicketNumber(ticketRaw) }),
+    ...(projectRoot === undefined ? {} : { projectRoot }),
+  };
+}