orizu 0.5.6 → 0.5.8

package/dist/manifests-cli.js

@@ -5,7 +5,7 @@
  * server — re-applying returns the stored outcome.
  */
 import { authedFetch } from './http.js';
-const MANIFEST_ACTIONS = new Set(['approve', 'reject', 'apply']);
+const MANIFEST_ACTIONS = new Set(['approve', 'reject', 'apply', 'revert']);
 async function responseMessage(response) {
     try {
         const data = (await response.clone().json());
@@ -73,6 +73,86 @@ function asRecord(value) {
 function num(value) {
     return typeof value === 'number' ? value : 0;
 }
+// Auto-applied manifests (ALI-1040) landed by SERVER POLICY, not a human approver
+// (approved_by is NULL). Mark them so a reviewer can tell policy applies from
+// human applies at a glance; the reason lives in the outcome for `show`.
+function wasAutoApplied(manifest) {
+    return asRecord(manifest.outcome).autoApplied === true;
+}
+/** STATUS cell: `applied*` when the server auto-applied it, else the raw status. */
+function statusDisplay(manifest) {
+    const status = typeof manifest.status === 'string' ? manifest.status : '(unknown)';
+    return wasAutoApplied(manifest) ? `${status}*` : status;
+}
+/** One-line auto-apply audit note for `show`, or null when not auto-applied. */
+function autoApplyNote(manifest) {
+    if (!wasAutoApplied(manifest))
+        return null;
+    const reason = asRecord(manifest.outcome).autoApplyReason;
+    return typeof reason === 'string' && reason.length > 0
+        ? `auto-applied by policy: ${reason}`
+        : 'auto-applied by policy';
+}
+// -- list table (ALI-1038) ----------------------------------------------------
+/** "3m" / "4h" / "2d" — enough resolution to pick a manifest out of a list. */
+function relativeAge(iso, now) {
+    if (typeof iso !== 'string')
+        return '-';
+    const then = Date.parse(iso);
+    if (Number.isNaN(then))
+        return '-';
+    const mins = Math.max(0, Math.floor((now - then) / 60_000));
+    if (mins < 60)
+        return `${mins}m`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+/** One-glance change summary from the stored proposedState — no live API call. */
+function changesSummary(manifest) {
+    if (manifest.actionType !== 'repo_merge')
+        return '-';
+    const proposed = asRecord(manifest.proposedState);
+    const files = num(proposed.filesChanged);
+    const parts = `${files} file${files === 1 ? '' : 's'} +${num(proposed.additions)}/-${num(proposed.deletions)}`;
+    // Instruction files steer agent behavior — reviewers should see the flag in the list.
+    return proposed.touches_instruction_files === true ? `${parts} !instr` : parts;
+}
+/** Reviewable-first (pending_approval, then draft), newest first within a group. */
+function listOrder(a, b) {
+    const rank = (m) => m.status === 'pending_approval' ? 0 : m.status === 'draft' ? 1 : 2;
+    const byRank = rank(a) - rank(b);
+    if (byRank !== 0)
+        return byRank;
+    const created = (m) => typeof m.createdAt === 'string' ? Date.parse(m.createdAt) || 0 : 0;
+    return created(b) - created(a);
+}
+/** Render manifests as the standard padEnd table (matches teams/projects list). */
+function manifestsTable(manifests, now) {
+    if (manifests.length === 0)
+        return 'promotion manifests\n(none)';
+    const rows = [...manifests].sort(listOrder).map(manifest => ({
+        id: typeof manifest.id === 'string' ? manifest.id : '(unknown)',
+        status: statusDisplay(manifest),
+        type: typeof manifest.actionType === 'string' ? manifest.actionType : '(unknown)',
+        changes: changesSummary(manifest),
+        author: typeof manifest.authorActorType === 'string' ? manifest.authorActorType : '-',
+        age: relativeAge(manifest.createdAt, now),
+    }));
+    const idWidth = Math.max('ID'.length, ...rows.map(row => row.id.length));
+    const statusWidth = Math.max('STATUS'.length, ...rows.map(row => row.status.length));
+    const typeWidth = Math.max('TYPE'.length, ...rows.map(row => row.type.length));
+    const changesWidth = Math.max('CHANGES'.length, ...rows.map(row => row.changes.length));
+    const authorWidth = Math.max('AUTHOR'.length, ...rows.map(row => row.author.length));
+    const header = `${'ID'.padEnd(idWidth)}  ${'STATUS'.padEnd(statusWidth)}  ${'TYPE'.padEnd(typeWidth)}  ` +
+        `${'CHANGES'.padEnd(changesWidth)}  ${'AUTHOR'.padEnd(authorWidth)}  AGE`;
+    const divider = `${'-'.repeat(idWidth)}  ${'-'.repeat(statusWidth)}  ${'-'.repeat(typeWidth)}  ` +
+        `${'-'.repeat(changesWidth)}  ${'-'.repeat(authorWidth)}  ---`;
+    const body = rows.map(row => `${row.id.padEnd(idWidth)}  ${row.status.padEnd(statusWidth)}  ${row.type.padEnd(typeWidth)}  ` +
+        `${row.changes.padEnd(changesWidth)}  ${row.author.padEnd(authorWidth)}  ${row.age}`);
+    return [header, divider, ...body].join('\n');
+}
 // repo_merge manifests (ALI-972) render the compare summary from stored evidence
 // — no live GitHub call — so a reviewer can approve informed without a PR.
 function repoMergeShow(manifest) {
@@ -108,7 +188,7 @@ export async function manifestsCommand(args, io) {
         const response = await fetcherFrom(io)(`/api/cli/promotion-manifests${query}`);
         const data = await requireOk(response, 'Manifest list');
         const manifests = Array.isArray(data.manifests) ? data.manifests : [];
-        emit(io, { manifests }, ['promotion manifests', ...manifests.map(manifestLine)].join('\n'));
+        emit(io, { manifests }, manifestsTable(manifests, Date.now()));
         return 0;
     }
     if (subcommand === 'show') {
@@ -119,7 +199,9 @@ export async function manifestsCommand(args, io) {
         const response = await fetcherFrom(io)(`/api/cli/promotion-manifests/${encodeURIComponent(id)}`);
         const data = await requireOk(response, 'Manifest show');
         const manifest = (data.manifest ?? {});
-        const human = manifest.actionType === 'repo_merge' ? repoMergeShow(manifest) : manifestLine(manifest);
+        const base = manifest.actionType === 'repo_merge' ? repoMergeShow(manifest) : manifestLine(manifest);
+        const note = autoApplyNote(manifest);
+        const human = note ? `${base}\n  ${note}` : base;
         emit(io, { manifest }, human);
         return 0;
     }
@@ -135,9 +217,25 @@ export async function manifestsCommand(args, io) {
         });
         const data = await requireOk(response, `Manifest ${subcommand}`);
         const manifest = (data.manifest ?? {});
-        emit(io, { manifest }, manifestLine(manifest));
+        const lines = [manifestLine(manifest)];
+        // Reject reaps the session branch best-effort; a failed reap must never be
+        // silent (ALI-1043) — surface it with the exact cleanup command.
+        if (subcommand === 'reject' && manifest.actionType === 'repo_merge') {
+            const outcome = asRecord(manifest.outcome);
+            const branch = asRecord(manifest.proposedState).branch;
+            if (outcome.branchDeleted === true) {
+                lines.push('session branch deleted');
+            }
+            else if (typeof branch === 'string' && branch.length > 0) {
+                lines.push(`warning: the session branch could not be deleted — remove it with: git push origin --delete ${branch}`);
+            }
+            else {
+                lines.push('warning: the session branch could not be deleted (branch name unavailable)');
+            }
+        }
+        emit(io, { manifest }, lines.join('\n'));
         return 0;
     }
-    io.print('Usage: orizu manifests <list|show|approve|reject|apply> ... [--json]');
+    io.print('Usage: orizu manifests <list|show|approve|reject|apply|revert> ... [--json]');
     return 1;
 }

package/dist/report-comments-cli.js

@@ -0,0 +1,325 @@
+const COMMENTS_TARGET_USAGE = 'Use exactly one of --prompt <id-or-name>, --run <run-id>, or --task <task-id>';
+function reportCommentsUsage(action) {
+    const target = '(--prompt <id-or-name> --project <team/project> [--label <label> | --version <id>] | --run <run-id> | --task <task-id>)';
+    if (action === 'list') {
+        return `Usage: orizu comments list ${target} [--json]`;
+    }
+    if (action === 'add') {
+        return `Usage: orizu comments add ${target} --body <text|@file> [--anchor <text>] [--lines <start:end>] [--via <name>] [--json]`;
+    }
+    if (action === 'reply') {
+        return 'Usage: orizu comments reply <comment-id> --body <text|@file> [--via <name>] [--json]';
+    }
+    if (action === 'edit') {
+        return 'Usage: orizu comments edit <comment-id> --body <text|@file> [--json]';
+    }
+    return `Usage: orizu comments ${action} <comment-id> [--json]`;
+}
+function compactTerminalText(ctx, value, maxLength = 160) {
+    const compact = ctx.sanitizeTerminalText(value).replace(/\s+/g, ' ').trim();
+    if (compact.length <= maxLength) {
+        return compact;
+    }
+    return `${compact.slice(0, Math.max(0, maxLength - 1)).trim()}…`;
+}
+async function readReportCommentError(ctx, response) {
+    const status = response.status
+        ? `HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}`
+        : 'request failed';
+    const contentType = response.headers.get('content-type') || '';
+    if (!contentType.toLowerCase().includes('application/json')) {
+        return status;
+    }
+    try {
+        const parsed = await response.clone().json();
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const error = parsed.error;
+            if (typeof error === 'string' && error.trim()) {
+                return compactTerminalText(ctx, error, 220);
+            }
+        }
+    }
+    catch {
+        // Fall through to the status-only message for malformed JSON errors.
+    }
+    return status;
+}
+function printIndentedBody(ctx, value, indent) {
+    const lines = ctx.sanitizeTerminalText(value || '').split(/\r?\n/);
+    for (const line of lines) {
+        ctx.printLine(`${indent}${line}`);
+    }
+}
+function formatReportCommentAnchor(ctx, anchor) {
+    if (!anchor) {
+        return null;
+    }
+    const lineLabel = anchor.startLine && anchor.endLine
+        ? anchor.startLine === anchor.endLine
+            ? `line ${anchor.startLine}`
+            : `lines ${anchor.startLine}-${anchor.endLine}`
+        : null;
+    const selectedText = anchor.text ? `"${compactTerminalText(ctx, anchor.text, 180)}"` : null;
+    if (lineLabel && selectedText) {
+        return `${lineLabel}: ${selectedText}`;
+    }
+    return lineLabel || selectedText;
+}
+function reportCommentAuthorName(author) {
+    const personName = author?.person?.name;
+    const name = personName || author?.name || 'Unknown';
+    const via = author?.via ? ` via ${author.via}` : '';
+    const agent = author?.actor === 'agent'
+        ? author.onBehalfOf
+            ? ` (agent on behalf of ${author.onBehalfOf})`
+            : ' (agent)'
+        : '';
+    return `${name}${via}${agent}`;
+}
+function printReportCommentSubject(ctx, data) {
+    if (data.prompt && data.version) {
+        const versionLabel = data.version.versionLabel || (data.version.versionNumber ? `v${data.version.versionNumber}` : data.version.id);
+        ctx.printLine(`Prompt: ${ctx.sanitizeTerminalText(data.prompt.name)} (${ctx.sanitizeTerminalText(data.prompt.id)})`);
+        ctx.printLine(`Version: ${ctx.sanitizeTerminalText(String(versionLabel))} (${ctx.sanitizeTerminalText(data.version.id)})`);
+        return;
+    }
+    if (data.run) {
+        ctx.printLine(`Optimization run: ${ctx.sanitizeTerminalText(data.run.id)}`);
+        return;
+    }
+    if (data.task) {
+        const title = data.task.title ? `${ctx.sanitizeTerminalText(data.task.title)} ` : '';
+        ctx.printLine(`Task: ${title}(${ctx.sanitizeTerminalText(data.task.id)})`);
+        return;
+    }
+    if (data.subject) {
+        ctx.printLine(`Subject: ${ctx.sanitizeTerminalText(data.subject.type)} ${ctx.sanitizeTerminalText(data.subject.id)}`);
+    }
+}
+function printReportComments(ctx, data) {
+    printReportCommentSubject(ctx, data);
+    ctx.printLine(`Comments: ${data.summary.threadCount} thread${data.summary.threadCount === 1 ? '' : 's'} ` +
+        `(${data.summary.openThreadCount} open, ${data.summary.resolvedThreadCount} resolved, ${data.summary.replyCount} replies)`);
+    if (data.comments.length === 0) {
+        ctx.printLine('\nNo comments found for this report.');
+        return;
+    }
+    for (const [index, thread] of data.comments.entries()) {
+        const authorName = reportCommentAuthorName(thread.author);
+        const anchor = formatReportCommentAnchor(ctx, thread.anchor);
+        ctx.printLine('');
+        ctx.printLine(`${index + 1}. [${thread.status}] ${ctx.sanitizeTerminalText(thread.id)} · ` +
+            `${ctx.sanitizeTerminalText(authorName)} · ${ctx.sanitizeTerminalText(thread.createdAt)}`);
+        if (thread.editedAt) {
+            ctx.printLine(`   Edited: ${ctx.sanitizeTerminalText(thread.editedAt)}`);
+        }
+        if (anchor) {
+            ctx.printLine(`   Selection: ${anchor}`);
+        }
+        printIndentedBody(ctx, thread.body, '   ');
+        if (thread.replies.length > 0) {
+            ctx.printLine(`   Replies (${thread.replies.length})`);
+            for (const reply of thread.replies) {
+                const replyAuthor = reportCommentAuthorName(reply.author);
+                ctx.printLine(`   - ${ctx.sanitizeTerminalText(reply.id)} · ` +
+                    `${ctx.sanitizeTerminalText(replyAuthor)} · ${ctx.sanitizeTerminalText(reply.createdAt)}`);
+                if (reply.editedAt) {
+                    ctx.printLine(`     Edited: ${ctx.sanitizeTerminalText(reply.editedAt)}`);
+                }
+                printIndentedBody(ctx, reply.body, '     ');
+            }
+        }
+    }
+}
+async function reportCommentsTargetParams(ctx, action) {
+    const promptRef = ctx.getArg('--prompt');
+    const runId = ctx.getArg('--run') || ctx.getArg('--run-id');
+    const taskId = ctx.getArg('--task');
+    ctx.rejectDashPrefixedOptionValue('--prompt', promptRef);
+    ctx.rejectDashPrefixedOptionValue('--run', runId);
+    ctx.rejectDashPrefixedOptionValue('--task', taskId);
+    const present = [
+        promptRef ? 'prompt' : null,
+        runId ? 'run' : null,
+        taskId ? 'task' : null,
+    ].filter(Boolean);
+    if (present.length !== 1) {
+        throw new Error(`${reportCommentsUsage(action)}\n${COMMENTS_TARGET_USAGE}`);
+    }
+    const params = new URLSearchParams();
+    if (promptRef) {
+        const project = ctx.getArg('--project') || await ctx.resolveProjectSlug(null);
+        const label = ctx.getArg('--label');
+        const version = ctx.getArg('--version');
+        ctx.rejectDashPrefixedOptionValue('--project', project);
+        ctx.rejectDashPrefixedOptionValue('--label', label);
+        ctx.rejectDashPrefixedOptionValue('--version', version);
+        if (label && version) {
+            throw new Error('Use either --label or --version, not both');
+        }
+        params.set('prompt', promptRef);
+        params.set('project', project);
+        if (label)
+            params.set('label', label);
+        if (version)
+            params.set('version', version);
+        return params;
+    }
+    if (runId) {
+        params.set('run', runId);
+        return params;
+    }
+    params.set('task', taskId);
+    return params;
+}
+function readReportCommentBodyInput(ctx, action) {
+    const body = ctx.getArg('--body');
+    ctx.rejectDashPrefixedOptionValue('--body', body);
+    if (!body) {
+        throw new Error(reportCommentsUsage(action));
+    }
+    if (body === '@') {
+        throw new Error('Usage: --body <text|@file>');
+    }
+    const value = body.startsWith('@') ? ctx.readSourceFile(body.slice(1)) : body;
+    if (!value.trim()) {
+        throw new Error('Comment body must not be blank');
+    }
+    return value;
+}
+function readReportCommentAnchorInput(ctx) {
+    const anchor = ctx.getArg('--anchor');
+    const lines = ctx.getArg('--lines');
+    ctx.rejectDashPrefixedOptionValue('--anchor', anchor);
+    ctx.rejectDashPrefixedOptionValue('--lines', lines);
+    let startLine = null;
+    let endLine = null;
+    if (lines) {
+        const match = lines.match(/^(\d+):(\d+)$/);
+        if (!match) {
+            throw new Error('--lines must use format <start:end>');
+        }
+        startLine = Number(match[1]);
+        endLine = Number(match[2]);
+        if (!Number.isInteger(startLine) || !Number.isInteger(endLine) || startLine < 1 || endLine < startLine) {
+            throw new Error('--lines must contain positive integers where end is greater than or equal to start');
+        }
+    }
+    if (!anchor && startLine === null) {
+        return null;
+    }
+    return {
+        text: anchor ? anchor.trim() : null,
+        startLine,
+        endLine,
+    };
+}
+function readReportCommentViaInput(ctx) {
+    const via = ctx.getArg('--via');
+    ctx.rejectDashPrefixedOptionValue('--via', via);
+    return via?.trim() || undefined;
+}
+async function listReportComments(ctx) {
+    const params = await reportCommentsTargetParams(ctx, 'list');
+    const response = await ctx.authedFetch(`/api/cli/report-comments?${params.toString()}`);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch report comments: ${await readReportCommentError(ctx, response)}`);
+    }
+    const data = await ctx.parseJsonResponse(response, 'Report comments');
+    if (ctx.hasJsonFlag()) {
+        ctx.printJson(data);
+        return;
+    }
+    printReportComments(ctx, data);
+}
+async function addReportComment(ctx) {
+    const params = await reportCommentsTargetParams(ctx, 'add');
+    const body = readReportCommentBodyInput(ctx, 'add');
+    const response = await ctx.authedFetch(`/api/cli/report-comments?${params.toString()}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            body,
+            via: readReportCommentViaInput(ctx),
+            anchor: readReportCommentAnchorInput(ctx),
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to add report comment: ${await readReportCommentError(ctx, response)}`);
+    }
+    const data = await ctx.parseJsonResponse(response, 'Report comment add');
+    if (ctx.hasJsonFlag()) {
+        ctx.printJson(data);
+        return;
+    }
+    ctx.printLine(`Added comment ${ctx.sanitizeTerminalText(data.comment.id)}`);
+}
+async function replyReportComment(ctx) {
+    const commentId = ctx.getPositionalArg(2);
+    if (!commentId) {
+        throw new Error(reportCommentsUsage('reply'));
+    }
+    const response = await ctx.authedFetch(`/api/cli/report-comments/${encodeURIComponent(commentId)}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            body: readReportCommentBodyInput(ctx, 'reply'),
+            via: readReportCommentViaInput(ctx),
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to reply to report comment: ${await readReportCommentError(ctx, response)}`);
+    }
+    const data = await ctx.parseJsonResponse(response, 'Report comment reply');
+    if (ctx.hasJsonFlag()) {
+        ctx.printJson(data);
+        return;
+    }
+    ctx.printLine(`Added reply ${ctx.sanitizeTerminalText(data.comment.id)} to ${ctx.sanitizeTerminalText(commentId)}`);
+}
+async function updateReportComment(ctx, action) {
+    const commentId = ctx.getPositionalArg(2);
+    if (!commentId) {
+        throw new Error(reportCommentsUsage(action));
+    }
+    const payload = action === 'edit'
+        ? { body: readReportCommentBodyInput(ctx, 'edit') }
+        : { resolved: action === 'resolve' };
+    const response = await ctx.authedFetch(`/api/cli/report-comments/${encodeURIComponent(commentId)}`, {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(payload),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to ${action} report comment: ${await readReportCommentError(ctx, response)}`);
+    }
+    const data = await ctx.parseJsonResponse(response, `Report comment ${action}`);
+    if (ctx.hasJsonFlag()) {
+        ctx.printJson(data);
+        return;
+    }
+    const verb = action === 'unresolve' ? 'Reopened' : action === 'edit' ? 'Edited' : 'Resolved';
+    ctx.printLine(`${verb} comment ${ctx.sanitizeTerminalText(data.comment.id)}`);
+}
+export async function reportCommentsCommand(action, ctx) {
+    if (action === 'list') {
+        await listReportComments(ctx);
+        return;
+    }
+    if (action === 'add') {
+        await addReportComment(ctx);
+        return;
+    }
+    if (action === 'reply') {
+        await replyReportComment(ctx);
+        return;
+    }
+    if (action === 'resolve' || action === 'unresolve' || action === 'edit') {
+        await updateReportComment(ctx, action);
+        return;
+    }
+    throw new Error('Usage: orizu comments <list|add|reply|resolve|unresolve|edit> ...');
+}
+export function throwDeprecatedPromptCommentsCommand() {
+    throw new Error('orizu prompts comments has moved. Use `orizu comments list --prompt <prompt-id-or-name> --project <team/project> [--label <label> | --version <id>]`.');
+}

package/dist/skill-installer.js

@@ -14,14 +14,17 @@ export const SKILL_INSTALL_TARGETS = [
     'codex-project',
     'claude-user',
     'claude-project',
+    'opencode-user',
+    'opencode-project',
     'agents-md',
 ];
 export const SKILL_META_FILENAME = '.orizu-skill-meta.json';
-export const SKILL_INSTALL_AGENTS = ['claude', 'codex'];
+export const SKILL_INSTALL_AGENTS = ['claude', 'codex', 'opencode'];
 const PROJECT_LEVEL_TARGETS = [
     'agents-project',
     'codex-project',
     'claude-project',
+    'opencode-project',
 ];
 function getCliRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -134,12 +137,24 @@ export function getSkillInstallPath(target, options) {
     if (target === 'claude-project') {
         return resolve(cwd, '.claude', 'skills', SKILL_NAME);
     }
+    // OpenCode discovers user skills under XDG config (~/.config/opencode/skills)
+    // and project skills under .opencode/skills (ALI-1044). The copy/link machinery
+    // is agent-neutral; only the destination path differs.
+    if (target === 'opencode-user') {
+        return resolve(home, '.config', 'opencode', 'skills', SKILL_NAME);
+    }
+    if (target === 'opencode-project') {
+        return resolve(cwd, '.opencode', 'skills', SKILL_NAME);
+    }
     return resolve(cwd, 'AGENTS.md');
 }
 export function getTargetForAgent(agent, scope) {
     if (agent === 'claude') {
         return scope === 'global' ? 'claude-user' : 'claude-project';
     }
+    if (agent === 'opencode') {
+        return scope === 'global' ? 'opencode-user' : 'opencode-project';
+    }
     return scope === 'global' ? 'codex-user' : 'agents-project';
 }
 export function isSkillInstallAgent(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orizu",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "private": false,
   "type": "module",
   "bin": {

package/src/credentials.ts

@@ -210,6 +210,52 @@ export function getActiveBaseUrl(): string | null {
   return config?.activeBaseUrl || null
 }
 
+/**
+ * In-sandbox bearer resolution (ALI-1044). Resolves a bearer supplied out-of-band
+ * to the hosted agent, WITHOUT consulting credentials.json:
+ *   1. `ORIZU_TOKEN` — an explicit bearer in the environment (wins if present).
+ *   2. `ORIZU_TOKEN_FILE` — an absolute path to a 0600 file whose TRIMMED contents
+ *      are the bearer.
+ * Returns null when neither is set, so callers fall through to credentials.json.
+ *
+ * The token file is read FRESH on EVERY call and never cached: the hosted loop
+ * ROTATES the file underneath a long-lived agent process, so caching the value
+ * would pin a stale (soon-expired) bearer. The token is never logged, echoed, or
+ * passed via argv — only returned to the caller for a single request's header.
+ *
+ * A set-but-unreadable/empty `ORIZU_TOKEN_FILE` throws a clear error rather than
+ * returning null, so a misconfigured sandbox fails loudly instead of silently
+ * falling back to (absent) credentials.json and emitting a confusing "not logged
+ * in" message.
+ */
+export function resolveEnvBearerToken(): string | null {
+  const explicit = process.env.ORIZU_TOKEN
+  if (explicit && explicit.trim()) {
+    return explicit.trim()
+  }
+
+  const tokenFile = process.env.ORIZU_TOKEN_FILE
+  if (tokenFile && tokenFile.length > 0) {
+    if (!existsSync(tokenFile)) {
+      throw new Error(`ORIZU_TOKEN_FILE is set to ${tokenFile} but no such file exists.`)
+    }
+    let raw: string
+    try {
+      raw = readFileSync(tokenFile, 'utf8')
+    } catch (error) {
+      const detail = isNodeError(error) ? error.message : String(error)
+      throw new Error(`Failed to read ORIZU_TOKEN_FILE (${tokenFile}): ${detail}`)
+    }
+    const token = raw.trim()
+    if (!token) {
+      throw new Error(`ORIZU_TOKEN_FILE (${tokenFile}) is empty.`)
+    }
+    return token
+  }
+
+  return null
+}
+
 export function setActiveBaseUrl(baseUrl: string | null) {
   const config = loadCredentialsConfigForWrite()
   config.activeBaseUrl = baseUrl