quoxcli 0.3.1 → 0.4.0

package/lib/commands/youtube.js

@@ -0,0 +1,172 @@
+/**
+ * `quox youtube` — YouTube plugin verbs, YT-O-6 (tiktok/linkedin CLI parity).
+ *
+ * quox youtube upload "<title>" --file <path-in-media-root> [--description t] [--privacy private|unlisted|public] [--thumbnail <image-path>]
+ * quox youtube thumbnail <videoId> --image <path-in-media-root>
+ * quox youtube videos [--limit <n>]
+ * quox youtube channel
+ * quox youtube analytics [--metrics a,b,c] [--video <id>]
+ * quox youtube comment <commentId> "<text>"
+ *
+ * The write verbs (upload, thumbnail, comment) execute the youtube connector
+ * tool through the governed collector endpoint (POST /api/v1/tools/execute ->
+ * connector bridge). The bridge gates them on requiresApproval: it files an
+ * owner approval card and returns { pending:true, status:'awaiting_approval',
+ * approvalId, inbox_item_id }. The YouTube API write only happens once an
+ * approver says yes (dashboard inbox or `quox inbox respond <id> --action approve`).
+ *
+ * Honest limit on --thumbnail: YouTube assigns the video id only when the
+ * upload actually executes, i.e. AFTER approval. While the upload card is
+ * pending there is no id to attach a thumbnail to, so the chained
+ * set_thumbnail step runs only if the upload came back executed with a
+ * video id; otherwise the CLI says so and names the follow-up verb.
+ */
+
+import { formatDetail, printSuccess, printInfo, printWarning } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+const PRIVACY = ['private', 'unlisted', 'public'];
+
+async function executeYouTubeTool({ client, auth, program }, toolName, input) {
+  auth.requireAuth();
+  const orgId = resolveOrgId(auth, program);
+  const ep = resolveEndpoint('v1.tools.execute');
+  const body = { tool_name: toolName, input, org_id: orgId };
+  const data = await client.post(ep.path, { service: ep.service, body });
+  if (data && data.success === false && !data.pending) {
+    throw new Error(`${toolName} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}`);
+  }
+  return data;
+}
+
+function printAwaitingApproval(action, data) {
+  const itemRef = data.inbox_item_id || data.approvalId || 'unknown';
+  printSuccess(`${action} filed for owner approval - inbox item ${itemRef} (awaiting approval). Nothing is sent to YouTube until an approver says yes.`);
+  if (data.inbox_item_id) {
+    printInfo(`Review and approve: quox inbox get ${data.inbox_item_id}  (or: quox inbox respond ${data.inbox_item_id} --action approve)`);
+  }
+}
+
+export function registerYouTubeCommands(program, ctx) {
+  const { client, auth } = ctx;
+  const run = (tool, input) => executeYouTubeTool({ client, auth, program }, tool, input);
+  const asJson = () => program.opts().output === 'json';
+
+  const youtube = program
+    .command('youtube')
+    .description('YouTube uploads, thumbnails, comments and reads: writes are governed and HITL-approved via HITL Inbox, on your own vaulted Google credential');
+
+  youtube
+    .command('upload')
+    .description('Upload a video from a file under the org media root. Files an owner approval card and returns immediately; never uploads directly.')
+    .argument('<title>', 'video title (max 100 characters)')
+    .requiredOption('--file <path>', 'video file path, relative to the org media root')
+    .option('--description <text>', 'video description')
+    .option('--privacy <status>', `privacy status: ${PRIVACY.join('|')} (default private)`, 'private')
+    .option('--thumbnail <path>', 'thumbnail image path (media root); chained set_thumbnail, only possible once the upload has a video id')
+    .action(async (title, options) => {
+      const privacy = options.privacy || 'private';
+      if (!PRIVACY.includes(privacy)) {
+        throw new Error(`--privacy must be one of ${PRIVACY.join(', ')} (got ${privacy})`);
+      }
+      const input = { title, file_path: options.file, privacy_status: privacy };
+      if (options.description) input.description = options.description;
+
+      const data = await run('youtube_upload_video', input);
+      const videoId = data?.result?.video_id || data?.video_id || null;
+      let thumb = null;
+      if (options.thumbnail && videoId && !data.pending) {
+        thumb = await run('youtube_set_thumbnail', { video_id: videoId, image_path: options.thumbnail });
+      }
+
+      if (asJson()) {
+        formatDetail(thumb ? { upload: data, thumbnail: thumb } : data, { format: 'json' });
+        return;
+      }
+      if (data.pending) {
+        printAwaitingApproval('Upload', data);
+        if (options.thumbnail) {
+          printWarning(`Thumbnail not filed: the video id does not exist until the upload is approved and runs. After approval run: quox youtube thumbnail <videoId> --image ${options.thumbnail}  (that files a second, separate approval).`);
+        }
+        return;
+      }
+      printSuccess(`Upload executed${videoId ? ` - video ${videoId}` : ''}.`);
+      if (thumb) {
+        if (thumb.pending) printAwaitingApproval('Thumbnail', thumb);
+        else printSuccess('Thumbnail set.');
+      } else if (options.thumbnail) {
+        printWarning(`Upload returned no video id, so the thumbnail was not set. Run: quox youtube thumbnail <videoId> --image ${options.thumbnail}`);
+      }
+    });
+
+  youtube
+    .command('thumbnail')
+    .description('Set a custom thumbnail on an existing video from an image under the org media root. Files an owner approval card; never sets it directly.')
+    .argument('<videoId>', 'YouTube video id')
+    .requiredOption('--image <path>', 'image path (.jpg/.jpeg/.png, max 2MB), relative to the org media root')
+    .action(async (videoId, options) => {
+      const data = await run('youtube_set_thumbnail', { video_id: videoId, image_path: options.image });
+      if (asJson()) { formatDetail(data, { format: 'json' }); return; }
+      printAwaitingApproval('Thumbnail', data);
+    });
+
+  youtube
+    .command('videos')
+    .description('List the connected channel\'s recent videos (read-only, no approval needed).')
+    .option('--limit <n>', 'max videos to return (max 50)', '20')
+    .action(async (options) => {
+      const count = Math.min(parseInt(options.limit, 10) || 20, 50);
+      const data = await run('youtube_list_videos', { count });
+      if (asJson()) { formatDetail(data, { format: 'json' }); return; }
+      const videos = data.result?.videos || [];
+      if (videos.length === 0) { printInfo('No videos returned.'); return; }
+      for (const v of videos) {
+        console.log(`${v.video_id}  ${v.title || '(no title)'}  [${v.privacy_status || 'unknown'}]`);
+        console.log(`  views: ${v.view_count ?? 0}  likes: ${v.like_count ?? 0}  comments: ${v.comment_count ?? 0}`);
+      }
+    });
+
+  youtube
+    .command('channel')
+    .description('Show the connected YouTube channel (also the cheapest live credential check).')
+    .action(async () => {
+      const data = await run('youtube_get_channel', {});
+      if (asJson()) { formatDetail(data, { format: 'json' }); return; }
+      const ch = data.result || {};
+      if (!ch.channel_id && !ch.title) { printInfo('No channel returned.'); return; }
+      console.log(`${ch.title || 'unknown'}  (${ch.channel_id || 'unknown'})`);
+      console.log(`  subscribers: ${ch.subscriber_count ?? 'unknown'}  videos: ${ch.video_count ?? 'unknown'}  views: ${ch.view_count ?? 'unknown'}`);
+    });
+
+  youtube
+    .command('analytics')
+    .description('Channel (or single video) analytics totals for the last 28 days.')
+    .option('--metrics <list>', 'comma-separated YouTube Analytics metric names (default views,estimatedMinutesWatched,averageViewDuration,likes,subscribersGained)')
+    .option('--video <id>', 'restrict to one video id')
+    .action(async (options) => {
+      const input = {};
+      if (options.metrics) input.metrics = options.metrics;
+      if (options.video) input.video_id = options.video;
+      const data = await run('youtube_get_analytics', input);
+      if (asJson()) { formatDetail(data, { format: 'json' }); return; }
+      const r = data.result || {};
+      const metrics = r.metrics || {};
+      const keys = Object.keys(metrics);
+      if (keys.length === 0) { printInfo('No analytics returned.'); return; }
+      console.log(`${r.start_date || '?'} to ${r.end_date || '?'}${r.video_id ? `  video ${r.video_id}` : ''}`);
+      for (const k of keys) console.log(`  ${k}: ${metrics[k]}`);
+      if (r.missing_metrics?.length) printWarning(`Not returned by YouTube: ${r.missing_metrics.join(', ')}`);
+    });
+
+  youtube
+    .command('comment')
+    .description('Reply to a comment thread. Files an owner approval card and returns immediately; never posts directly.')
+    .argument('<commentId>', 'comment thread id to reply to (the id of the top-level comment)')
+    .argument('<text>', 'reply text')
+    .action(async (parentId, text) => {
+      const data = await run('youtube_reply_comment', { parent_id: parentId, text });
+      if (asJson()) { formatDetail(data, { format: 'json' }); return; }
+      printAwaitingApproval('Comment reply', data);
+    });
+}

package/lib/core/actionItems.js

@@ -0,0 +1,115 @@
+/**
+ * Action Tracker item writes and open-item reads, shared by `quox actions
+ * add|done` and the Quox TUI /todo and /todos. One core, so chat, CLI and TUI
+ * create the same item through the same collector route
+ * (POST /api/v1/actions, PATCH /api/v1/actions/:id), as the logged-in user.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxError } from './errors.js';
+
+export const PRIORITIES = ['low', 'medium', 'high', 'urgent'];
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+
+const pad = (n) => String(n).padStart(2, '0');
+const dayOf = (d) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+
+/** "today", "tomorrow" or YYYY-MM-DD -> YYYY-MM-DD. Anything else is a usage error, never guessed. */
+export function parseDue(value, now = new Date()) {
+  if (value === undefined || value === null || value === '') return null;
+  const v = String(value).trim().toLowerCase();
+  if (v === 'today') return dayOf(now);
+  if (v === 'tomorrow') return dayOf(new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1));
+  if (ISO_DAY.test(v) && !Number.isNaN(Date.parse(`${v}T00:00:00Z`))) return v;
+  throw new QuoxError(`--due must be YYYY-MM-DD, today or tomorrow (got "${value}")`, 2);
+}
+
+/** Words typed after the verb -> a title. Empty or blank is a usage error. */
+export function titleFromWords(words) {
+  const title = (Array.isArray(words) ? words.join(' ') : String(words || '')).trim();
+  if (!title) throw new QuoxError('Usage: quox actions add <text...> [--due <date>] [--priority low|medium|high|urgent]', 2);
+  return title;
+}
+
+/** Throw unless the response carries an item with an id: an error body is never a created item. */
+function itemOf(res, what) {
+  const item = res && res.item;
+  if (!item || !item.id || res.success === false) {
+    throw new QuoxError(`${what} failed: ${(res && (res.error || res.message)) || 'the server returned no item'}`);
+  }
+  return item;
+}
+
+/** Create one Action Tracker item (status todo) as the logged-in user. -> the item. */
+export async function addActionItem(client, { title, due, priority, description } = {}) {
+  const t = titleFromWords(title);
+  if (priority && !PRIORITIES.includes(priority)) {
+    throw new QuoxError(`--priority must be one of ${PRIORITIES.join(', ')}`, 2);
+  }
+  const body = { title: t };
+  const dueDate = parseDue(due);
+  if (dueDate) body.due_date = dueDate;
+  if (priority) body.priority = priority;
+  if (description) body.description = description;
+  const ep = resolveEndpoint('actions.create');
+  return itemOf(await client.post(ep.path, { service: ep.service, body }), 'Adding the action item');
+}
+
+export const STATUS_COLUMNS = ['todo', 'doing', 'done'];
+
+/** Move one item to todo, doing or done. -> the item. */
+export async function moveActionItem(client, id, status) {
+  const clean = String(id || '').trim();
+  if (!clean) throw new QuoxError('Usage: quox actions move <id> <todo|doing|done>', 2);
+  if (!STATUS_COLUMNS.includes(status)) throw new QuoxError(`status must be one of ${STATUS_COLUMNS.join(', ')}`, 2);
+  const ep = resolveEndpoint('actions.update', { id: clean });
+  return itemOf(await client.patch(ep.path, { service: ep.service, body: { status } }), 'Moving the action item');
+}
+
+/** Mark one item done. -> the item. */
+export async function completeActionItem(client, id) {
+  if (!String(id || '').trim()) throw new QuoxError('Usage: quox actions done <id>', 2);
+  return moveActionItem(client, id, 'done');
+}
+
+/** Every item in one column (or all), paged to the end; never a silent cap. -> [{id,title,status,priority,due_date}]. */
+export async function listActionItems(client, status = 'all', { pageSize = 100, maxPages = 50 } = {}) {
+  const ep = resolveEndpoint('actions.list');
+  const out = [];
+  for (let page = 1; page <= maxPages; page++) {
+    const query = { limit: pageSize, page };
+    if (status !== 'all') query.status = status;
+    const res = await client.get(ep.path, { service: ep.service, query, retries: 0 });
+    if (!res || !Array.isArray(res.items)) {
+      throw new QuoxError(`Listing action items failed: ${(res && (res.error || res.message)) || 'unexpected response'}`);
+    }
+    out.push(...res.items);
+    if (!(res.pagination && res.pagination.has_more)) return out;
+  }
+  throw new QuoxError(`More than ${maxPages * pageSize} action items; narrow with quox actions list --status.`);
+}
+
+/** The board by column. -> { backlog (status todo), doing, done } each a full list. */
+export async function listBoard(client) {
+  const backlog = await listActionItems(client, 'todo');
+  const doing = await listActionItems(client, 'doing');
+  const done = await listActionItems(client, 'done');
+  return { backlog, doing, done };
+}
+
+/** Open items (todo then doing), all of them. */
+export async function listOpenActionItems(client) {
+  return [...(await listActionItems(client, 'todo')), ...(await listActionItems(client, 'doing'))];
+}
+
+/** Delete one item (server soft-deletes; creator or admin only). Checks the status before trusting the body. -> { id, title }. */
+export async function deleteActionItem(client, id) {
+  const clean = String(id || '').trim();
+  if (!clean) throw new QuoxError('Usage: quox actions delete <id> --yes', 2);
+  const ep = resolveEndpoint('actions.delete', { id: clean });
+  const res = await client.delete(ep.path, { service: ep.service });
+  if (!res || res.success === false || res.deleted !== true) {
+    throw new QuoxError(`Deleting the action item failed: ${(res && (res.error || res.message)) || 'the server did not confirm the delete'}`);
+  }
+  return { id: clean, title: res.title || '' };
+}

package/lib/core/agentAlias.js

@@ -58,6 +58,8 @@ export function loadBundledAssistantsRoster(dir = DEFAULT_ASSISTANTS_DIR) {
           id: raw.id,
           name: raw.identity?.name || null,
           shortName: raw.identity?.shortName || null,
+          // AGENT-TAXONOMY: present only when the file declares one.
+          ...(raw.family ? { family: raw.family } : {}),
         });
       }
     } catch {

package/lib/core/agentFamilies.js

@@ -0,0 +1,7 @@
+// Agent family ids, mirrored from src/config/agentFamilies.js (the authority).
+// The published CLI does not ship src/config, so it keeps this copy;
+// cli/test/core/agentFamilies.test.js fails if the two drift.
+export const AGENT_FAMILY_IDS = [
+  'command', 'devops', 'monitoring', 'secops', 'development',
+  'assistantq', 'knowledge', 'marketing', 'voice', 'governance',
+];

package/lib/core/client.js

@@ -115,6 +115,14 @@ export function createClient(config, auth) {
   // never tried again for the rest of its life). A cooldown keeps the
   // don't-hammer-auth property without the death sentence.
   const REFRESH_RETRY_COOLDOWN_MS = 60 * 1000;
+  // quox#1375: a profile with nothing to refresh with (the collector's quox_cli hop writes only the caller's access
+  // token) must surface the route's own 401, not "Session expired... No refresh token", which hid the real cause.
+  // A token-file principal re-mints its own file and a resident re-auths by signed challenge, so both still refresh.
+  const canRefresh = () => {
+    if (process.env.QUOX_TOKEN_FILE) return true;
+    const a = typeof config.getAuth === 'function' ? config.getAuth() : null;
+    return !!(a && (a.refresh_token || a.kind === 'resident'));
+  };
   let refreshFailedAt = 0;
   const correlationId = generateCorrelationId();
 
@@ -291,7 +299,7 @@ export function createClient(config, auth) {
         }
 
         const refreshCoolingDown = refreshFailedAt && (Date.now() - refreshFailedAt < REFRESH_RETRY_COOLDOWN_MS);
-        if (res.status === 401 && !noAuth && !actingAs && !refreshedThisRequest && !refreshCoolingDown && looksExpired) {
+        if (res.status === 401 && !noAuth && !actingAs && !refreshedThisRequest && !refreshCoolingDown && looksExpired && canRefresh()) {
           refreshedThisRequest = true;
           try {
             if (!refreshing) {
@@ -575,7 +583,7 @@ export function createClient(config, auth) {
         try { looksExpired = (await res.clone().json())?.error === 'invalid_token'; } catch { /* non-JSON body */ }
       }
       const refreshCoolingDown = refreshFailedAt && (Date.now() - refreshFailedAt < REFRESH_RETRY_COOLDOWN_MS);
-      if (looksExpired && !refreshCoolingDown) {
+      if (looksExpired && !refreshCoolingDown && canRefresh()) {
         try {
           if (!refreshing) {
             refreshing = auth.refresh(config.getServiceUrl('auth')).finally(() => { refreshing = null; });

package/lib/core/commandRegistrars.js

@@ -12,6 +12,7 @@ export const COMMAND_REGISTRARS = [
   ['../commands/doctor.js', 'registerDoctorCommand'],
   ['../commands/server.js', 'registerServerCommands'],
   ['../commands/update.js', 'registerUpdateCommand'],
+  ['../commands/shortcut.js', 'registerShortcutCommand'],
   ['../commands/open.js', 'registerOpenCommand'],
   ['../commands/peek.js', 'registerPeekCommand'],
   ['../commands/aside.js', 'registerAsideCommand'],
@@ -26,6 +27,7 @@ export const COMMAND_REGISTRARS = [
   ['../commands/tool.js', 'registerToolCommands'],
   ['../commands/workflow.js', 'registerWorkflowCommands'],
   ['../commands/objective.js', 'registerObjectiveCommands'],
+  ['../commands/loop.js', 'registerLoopCommands'],
   ['../commands/assistant.js', 'registerAssistantCommands'],
   ['../commands/fleet.js', 'registerFleetCommands'],
   ['../commands/chat.js', 'registerChatCommands'],
@@ -41,10 +43,12 @@ export const COMMAND_REGISTRARS = [
   ['../commands/mail.js', 'registerMailCommands'],
   ['../commands/calendar.js', 'registerCalendarCommands'],
   ['../commands/notes.js', 'registerNotesCommands'],
+  ['../commands/blog.js', 'registerBlogCommands'],
   ['../commands/contacts.js', 'registerContactsCommands'],
   ['../commands/licence.js', 'registerLicenceCommands'],
   ['../commands/run.js', 'registerRunCommands'],
   ['../commands/file.js', 'registerFileCommands'],
+  ['../commands/evidence.js', 'registerEvidenceCommands'],
   ['../commands/admin.js', 'registerAdminCommands'],
   ['../commands/aee.js', 'registerAeeCommands'],
   ['../commands/integration.js', 'registerIntegrationCommands'],
@@ -80,10 +84,12 @@ export const COMMAND_REGISTRARS = [
   ['../commands/capabilities.js', 'registerCapabilitiesCommands'],
   ['../commands/provider.js', 'registerProviderCommands'],
   ['../commands/tips.js', 'registerTipsCommands'],
+  ['../commands/ext.js', 'registerExtCommands'],
   ['../commands/quoxchat.js', 'registerQuoxchatCommands'],
   ['../commands/budget.js', 'registerBudgetCommands'],
   ['../commands/trace.js', 'registerTraceCommands'],
   ['../commands/mon.js', 'registerMonCommands'],
+  ['../commands/kuma.js', 'registerKumaCommands'],
   ['../commands/quoxbox.js', 'registerQuoxboxCommands'],
   ['../commands/plan.js', 'registerPlanCommands'],
   ['../commands/engagement.js', 'registerEngagementCommands'],
@@ -91,6 +97,7 @@ export const COMMAND_REGISTRARS = [
   ['../commands/discord.js', 'registerDiscordCommands'],
   ['../commands/qlarity.js', 'registerQlarityCommands'],
   ['../commands/fetchAllowlist.js', 'registerFetchAllowlistCommands'],
+  ['../commands/research.js', 'registerResearchCommands'],
   ['../commands/reach.js', 'registerReachCommands'],
   ['../commands/inventory.js', 'registerInventoryCommands'],
   ['../commands/policy.js', 'registerPolicyCommands'],
@@ -115,6 +122,8 @@ export const COMMAND_REGISTRARS = [
   ['../commands/facebook.js', 'registerFacebookCommands'],
   ['../commands/instagram.js', 'registerInstagramCommands'],
   ['../commands/tiktok.js', 'registerTikTokCommands'],
+  ['../commands/youtube.js', 'registerYouTubeCommands'],
+  ['../commands/image.js', 'registerImageCommands'],
   ['../commands/offload.js', 'registerOffloadCommands'],
 ];
 

package/lib/core/config.js

@@ -220,7 +220,7 @@ export function deriveServiceUrl(baseUrl, port, service, opts = {}) {
 // only correct source for the flag at ctx-build time.
 // Commands whose remaining argv belongs to another program (`quox claude -p
 // "prompt"` is claude's --print, not quox's --profile).
-const WRAPPED_PROGRAM_COMMANDS = new Set(['claude', 'codex', 'gemini', 'wrap']);
+const WRAPPED_PROGRAM_COMMANDS = new Set(['claude', 'codex', 'wrap']);
 
 export function resolveProfileFlagFromArgv(argv) {
   for (let i = 0; i < argv.length; i++) {

package/lib/core/findingReconcile.js

@@ -0,0 +1,90 @@
+/**
+ * SITREP-FINDINGS: gather the evidence that a security finding was fixed, on the host where
+ * git and gh live, for `quox engagement reconcile`. The collector makes the decision
+ * (securityFindings.reconcileFinding); this module only finds facts and never guesses:
+ *   - issue: the stored issue_ref, the gripe_url Quox filed, a --link, or quox#N / #N in the
+ *     title (quox#N in the description). Its state comes from `gh issue view`; unreadable = left out.
+ *   - fix: commits on origin/main whose message cites the finding id or the linked issue
+ *     number, or a --link commit. landed = an ancestor of origin/main; deployed = an ancestor of
+ *     the build tree's HEAD (the tree quox-build last built from). A commit not on main is no fix.
+ */
+
+const GH_ISSUE_URL = /github\.com\/([\w.-]+)\/([\w.-]+)\/issues\/(\d+)/;
+
+export function issueRefsFor(finding, link = {}, issueRepo = 'quoxai/quox') {
+  const out = [];
+  const add = (r) => { if (r && !out.includes(r)) out.push(r); };
+  if (finding.issue_ref) add(finding.issue_ref);
+  const m = GH_ISSUE_URL.exec(finding.gripe_url || '');
+  if (m) add(`${m[1]}/${m[2]}#${m[3]}`);
+  if (link.issue) add(normIssue(link.issue, issueRepo));
+  const t = /(?:quox)?#(\d{1,6})\b/.exec(String(finding.title || ''));
+  if (t) add(`${issueRepo}#${t[1]}`);
+  const d = /\bquox#(\d{1,6})\b/.exec(String(finding.description || ''));
+  if (d) add(`${issueRepo}#${d[1]}`);
+  return out;
+}
+
+export function normIssue(ref, issueRepo = 'quoxai/quox') {
+  const s = String(ref).trim();
+  const m = GH_ISSUE_URL.exec(s);
+  if (m) return `${m[1]}/${m[2]}#${m[3]}`;
+  if (/^[\w.-]+\/[\w.-]+#\d+$/.test(s)) return s;
+  const n = /^(?:quox)?#?(\d+)$/.exec(s);
+  return n ? `${issueRepo}#${n[1]}` : null;
+}
+
+function issueState(ref, run) {
+  const [repo, n] = ref.split('#');
+  const r = run('gh', ['issue', 'view', n, '-R', repo, '--json', 'state']);
+  if (!r.ok) return null;
+  try {
+    const st = String(JSON.parse(r.out).state || '').toLowerCase();
+    return st === 'open' || st === 'closed' ? st : null;
+  } catch { return null; }
+}
+
+function commitsCiting(term, regex, { repoDir, run }) {
+  const r = run('git', ['-C', repoDir, 'log', 'origin/main', '--format=%H', ...(regex ? ['-E'] : ['--fixed-strings']), `--grep=${term}`]);
+  if (!r.ok) return [];
+  return r.out.split('\n').map((x) => x.trim()).filter((x) => /^[0-9a-f]{40}$/i.test(x));
+}
+
+export function gatherEvidence(finding, link = {}, { repoDir, buildDir, issueRepo = 'quoxai/quox', run }) {
+  const ev = {};
+  const refs = issueRefsFor(finding, link, issueRepo);
+  if (refs.length) {
+    ev.issue_ref = refs[0];
+    const st = issueState(refs[0], run);
+    if (st) ev.issue_state = st;
+  }
+
+  const shas = [];
+  const add = (s) => { if (s && !shas.includes(s)) shas.push(s); };
+  if (link.commit) {
+    const full = run('git', ['-C', repoDir, 'rev-parse', '--verify', `${link.commit}^{commit}`]);
+    add(full.ok && /^[0-9a-f]{40}$/i.test(full.out.trim()) ? full.out.trim() : link.commit);
+  }
+  if (finding.fix_commit) add(finding.fix_commit);
+  for (const s of commitsCiting(finding.id, false, { repoDir, run })) add(s);
+  if (ev.issue_ref && ev.issue_ref.startsWith(`${issueRepo}#`)) {
+    const n = ev.issue_ref.split('#')[1];
+    for (const s of commitsCiting(`#${n}([^0-9]|$)`, true, { repoDir, run })) add(s);
+  }
+  if (!shas.length) return ev;
+
+  const head = run('git', ['-C', buildDir, 'rev-parse', 'HEAD']);
+  const buildHead = head.ok ? head.out.trim() : null;
+  const isAnc = (dir, sha, tip) => run('git', ['-C', dir, 'merge-base', '--is-ancestor', sha, tip]).ok;
+  const landed = shas.filter((s) => isAnc(repoDir, s, 'origin/main'));
+  const deployed = buildHead ? landed.filter((s) => isAnc(buildDir, s, buildHead)) : [];
+  if (deployed.length) { ev.fix_commit = deployed[0]; ev.fix_state = 'deployed'; } else if (landed.length) { ev.fix_commit = landed[0]; ev.fix_state = 'landed'; }
+  return ev;
+}
+
+export function evidenceChanged(finding, ev) {
+  for (const k of ['issue_ref', 'issue_state', 'fix_commit', 'fix_state']) {
+    if (ev[k] != null && ev[k] !== (finding[k] ?? null)) return true;
+  }
+  return false;
+}

package/lib/core/global-flags.js

@@ -87,7 +87,7 @@ const HONOURS_GLOBAL_DRY_RUN = Symbol.for('quox.forwardsRawArgs');
 /**
  * Mark a leaf that honours a --dry-run WITHOUT declaring its own option,
  * because it forwards every raw argv token after its verb word to a wrapped
- * tool (claude, codex, gemini, wrap). Such a leaf honours the flag only when
+ * tool (claude, codex, wrap). Such a leaf honours the flag only when
  * it is typed AFTER the verb (it then reaches the wrapped tool); typed before
  * the verb it reaches nothing, so it is refused like any other.
  */

package/lib/core/governedSession.js

@@ -37,8 +37,6 @@ export function autoName(now = new Date()) {
 export const PROGRAMS = {
   claude: { tag: '', bin: 'claude', resumeHint: (n) => `quox claude --resume ${n}` },
   codex: { tag: 'codex-', bin: 'codex', resumeHint: (n) => `quox codex resume ${n}` },
-  // gemini resumes by index or "latest" (--resume latest | --resume N), not by name.
-  gemini: { tag: 'gemini-', bin: 'gemini', resumeHint: () => 'quox gemini --resume latest' },
   tui: { tag: 'tui-', bin: 'quox', resumeHint: (n) => `quox tui --governed --name ${n}` },
 };
 
@@ -335,7 +333,7 @@ export function runLs(over) {
     return 1;
   }
   if (!s.length) {
-    d.write('No Quox sessions running. Start one with: quox claude (or quox codex, quox gemini, quox wrap <program>)\n');
+    d.write('No Quox sessions running. Start one with: quox claude (or quox codex, quox wrap <program>)\n');
     return 0;
   }
   const pad = (v, n) => String(v).padEnd(n);

package/lib/core/liveSessionsReport.js

@@ -10,7 +10,7 @@ import { spawnSync } from 'node:child_process';
 
 export const TMUX_FORMAT = '#{session_name}\t#{session_created}\t#{session_attached}\t#{pane_current_command}\t#{pane_pid}\t#{session_activity}';
 
-const AGENT_PROGRAMS = new Set(['claude', 'codex', 'gemini']);
+const AGENT_PROGRAMS = new Set(['claude', 'codex']);
 
 /** Parse `tmux list-panes -a -F TMUX_FORMAT` output; one entry per session (first pane wins). */
 export function parseTmuxPanes(out) {

package/lib/core/loopGlyph.js

@@ -0,0 +1,97 @@
+/**
+ * QLOOP-LIVE: render loop events as QuoxGlyph lines (`quox loop watch`).
+ *   ∞ QLOOP │ turn 3/10 │ wrote report.md · 41s ✔
+ *
+ * Pure: event in, string out, so the watch loop, the tests and anything else that wants the same
+ * voice (the TUI card's observe lines) share one renderer. The ∞ icon is claimed here by extending
+ * the exported registry at import time (the vendored quoxglyph.js is source-locked to the package).
+ */
+
+import { ICONS, STATUS, brandName } from './quoxglyph.js';
+
+ICONS.qloop = '∞ QLOOP';
+
+const R = '\x1b[0m', DIM = '\x1b[2m';
+const colourOn = () => brandName('x y') !== 'x y';
+
+function oneLine(s, n) {
+  const t = String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+  return [...t].length > n ? `${[...t].slice(0, n - 1).join('')}…` : t;
+}
+
+/** "41s", "1m12s", "2h03m" */
+export function elapsedLabel(ms) {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}s`;
+  return `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, '0')}m`;
+}
+
+/** One QLOOP line: icon+name, verb, optional result, optional status glyph. Result is NOT budget-truncated here (callers cap it). */
+export function loopLine(verb, result, status) {
+  const col = colourOn();
+  const sep = col ? `${DIM}│${R}` : '│';
+  let out = `${brandName(ICONS.qloop)} ${sep} ${verb}`;
+  if (result) out += ` ${sep} ${result}`;
+  const s = status && STATUS[status];
+  if (s) out += ' ' + (col && s.rgb ? `\x1b[38;2;${s.rgb[0]};${s.rgb[1]};${s.rgb[2]}m${s.glyph}${R}` : s.glyph);
+  return out;
+}
+
+const OBSERVE_STATUS = { interval: 'busy', milestone: 'ok', error: 'fail', approval: 'warn', stall: 'warn' };
+
+/**
+ * @param {object} e   a loop event (design section 1)
+ * @param {object} ctx { title, maxTurns, startedMs, spool }
+ * @returns {string[]} lines to print (may be empty)
+ */
+export function renderEvent(e, ctx = {}) {
+  const max = ctx.maxTurns ? `/${ctx.maxTurns}` : '';
+  const since = ctx.startedMs ? ` · ${elapsedLabel(Date.parse(e.at) - ctx.startedMs)}` : '';
+  switch (e.type) {
+    case 'loop.started': {
+      const scope = Array.isArray(e.scope) && e.scope.length ? e.scope.join(',') : 'none';
+      return [loopLine('started', `host ${e.host} · ${e.backend} · scope ${oneLine(scope, 60)}${e.max_turns ? ` · ${e.max_turns} turns max` : ''}`, 'busy')];
+    }
+    case 'loop.turn.started':
+      return ctx.spool ? [loopLine(`turn ${e.turn}${max}`, 'working', 'busy')] : [];
+    case 'loop.turn.output':
+      return ctx.spool ? String(e.chunk).replace(/\n+$/, '').split('\n').map((l) => `  │ ${l}`) : [];
+    case 'loop.turn.tool': {
+      if (e.note) return [loopLine(`turn ${e.turn}`, `${e.tool} no result (${oneLine(e.note, 60)})${since}`, 'warn')];
+      if (e.denied) return [loopLine(`turn ${e.turn}`, `${e.tool} denied: ${oneLine(e.denied, 60)}${since}`, 'warn')];
+      return [loopLine(`turn ${e.turn}`, `${e.tool} ${e.ok ? 'ok' : 'failed'}${e.ms ? ` ${e.ms}ms` : ''}${since}`, e.ok ? 'ok' : 'fail')];
+    }
+    case 'loop.turn.completed':
+      return [loopLine(`turn ${e.turn}${max}`, `${oneLine(e.summary, 70)}${since}`, 'ok')];
+    case 'loop.observe':
+      if (e.kind === 'milestone') return [loopLine('milestone', oneLine(e.text, 100), 'ok')];
+      return [loopLine(e.kind === 'interval' ? 'status' : e.kind, oneLine(e.text, 110), OBSERVE_STATUS[e.kind] || 'busy')];
+    case 'loop.ward':
+      if (e.status === 'pending') return []; // announced, not yet witnessed: nothing to say yet
+      return [loopLine('receipt', `${String(e.envelope_id).slice(0, 12)} ${e.status}`, e.status === 'WITNESSED' ? 'ok' : 'warn')];
+    case 'loop.approval':
+      return [loopLine('approval', `${oneLine(e.what, 90)} (${e.checkpoint_id})`, 'warn')];
+    case 'loop.finished': {
+      // Only a clean completion is a tick. completed_with_errors and a halt / interruption warn; a failure fails. The reason is
+      // whole (a wrapped line beats a cut sentence) and loses the raw component prefix the spawner puts first.
+      const status = e.state === 'completed' ? 'ok' : e.state === 'failed' ? 'fail' : 'warn';
+      const wit = e.receipts != null ? `, ${e.witnessed}/${e.receipts} witnessed` : '';
+      const reason = String(e.reason || '').replace(/\s+/g, ' ').trim().replace(/^[a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*:\s+/, '');
+      const why = e.state !== 'completed' && reason ? `: ${reason}` : '';
+      return [loopLine(oneLine(ctx.title || 'loop', 48), `${e.state}, ${e.turns} turn${e.turns === 1 ? '' : 's'}${wit}${why}`, status)];
+    }
+    default:
+      return [];
+  }
+}
+
+/** Exit code for a finished loop: 0 completed (also with errors), 1 failed, 2 halted by a human, 3 interrupted. */
+export function exitCodeFor(state) {
+  switch (state) {
+    case 'completed': case 'completed_with_errors': return 0;
+    case 'halted': return 2;
+    case 'interrupted': return 3;
+    default: return 1;
+  }
+}