@elalfner/relevo 0.3.1 → 0.5.0

package/scripts/lib/go-local.mjs

@@ -5,16 +5,38 @@
 //   capture(cmd, args, { cwd }) -> stdout (throws when the command fails)
 //   stream(cmd, args, { cwd, env }) -> exit status (the output goes to the terminal); throws with code ENOENT when missing
 
+import { tmpdir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { cloudBuilds } from './execution-mode.mjs';
 import { runFlags } from './run-flags.mjs';
 
 export const WORKTREES_FOLDER = '.relevo-worktrees';
+// The guard is part of the plugin, not of the project that is built, so it is found next to this file.
+const GUARD = fileURLToPath(new URL('../agent-guard.mjs', import.meta.url));
+// The same time limit as the cloud step of the Antigravity agent.
+export const GUARD_TIMEOUT_MINUTES = 50;
 
-/** What a local run will do, without doing it: the worktree and the `claude` command. Pure. */
+/** What a local run will do, without doing it: the worktree and the `claude` or `agy` command. Pure. */
 export function planLocalRun({ issue, repoRoot, config }) {
   const base = config.branches.base;
   const worktree = join(dirname(repoRoot), WORKTREES_FOLDER, `${basename(repoRoot)}-${issue}`);
+  const isAntigravity = config.agent?.build === 'antigravity';
+  const command = isAntigravity
+    ? ['node', [
+        GUARD,
+        'run',
+        '--prompt',
+        `/relevo:go ${issue}`,
+        '--config',
+        'relevo.yml',
+        '--timeout-minutes',
+        String(GUARD_TIMEOUT_MINUTES),
+        // outside the worktree, so a clean end can remove it and the agent finds the tree clean
+        '--summary',
+        join(tmpdir(), `relevo-guard-${basename(repoRoot)}-${issue}.json`),
+      ]]
+    : ['claude', ['-p', `/relevo:go ${issue}`, ...runFlags(config)]];
   return {
     issue,
     base,
@@ -23,9 +45,9 @@ export function planLocalRun({ issue, repoRoot, config }) {
       ['fetch', 'origin', base],
       ['worktree', 'add', '--detach', worktree, `origin/${base}`],
     ],
-    claude: ['claude', ['-p', `/relevo:go ${issue}`, ...runFlags(config)]],
+    claude: command,
     // Without this the agent may start a subagent in the background and end the run before it finishes.
-    env: { CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1' },
+    env: isAntigravity ? {} : { CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1' },
   };
 }
 
@@ -45,6 +67,7 @@ export function runLocal({ issue, config, runner, workflowPresent = false, dryRu
     return { status: 2, worktree: null, removed: false, messages: ['not inside a git repository'] };
   }
   const plan = planLocalRun({ issue: String(issue), repoRoot, config });
+  const isAntigravity = config.agent?.build === 'antigravity';
 
   if (dryRun) {
     say(`worktree: ${plan.worktree} (from origin/${plan.base})`);
@@ -84,7 +107,10 @@ export function runLocal({ issue, config, runner, workflowPresent = false, dryRu
     status = runner.stream(plan.claude[0], plan.claude[1], { cwd: plan.worktree, env: plan.env });
   } catch (err) {
     status = err.code === 'ENOENT' ? 127 : 1;
-    say(err.code === 'ENOENT' ? 'the claude command was not found: install Claude Code and the Relevo plugin' : `the run could not start: ${err.message}`);
+    const missing = config.agent?.build === 'antigravity'
+      ? 'the agy or node command was not found: install the Antigravity CLI'
+      : 'the claude command was not found: install Claude Code and the Relevo plugin';
+    say(err.code === 'ENOENT' ? missing : `the run could not start: ${err.message}`);
   }
 
   if (status === 0) {
@@ -97,6 +123,7 @@ export function runLocal({ issue, config, runner, workflowPresent = false, dryRu
       return { status: 0, worktree: plan.worktree, removed: false, messages };
     }
   }
+  if (isAntigravity && status === 2) say('the run guard refused to start (usage error): see its message above');
   say(`the run ended with status ${status}; the worktree is kept for inspection: ${plan.worktree}`);
   return { status, worktree: plan.worktree, removed: false, messages };
 }

package/scripts/lib/init-tools.mjs

@@ -0,0 +1,97 @@
+// `relevo init`: set up Relevo for the tools a team uses, in the project or on the machine, and `relevo update` for the
+// plugins that were rendered. Claude Code keeps being installed by `claude plugin` (see cli.mjs); another tool gets a
+// plugin rendered from the same sources (see adapters/). Everything that talks to the outside is injected.
+import { execute } from './cli.mjs';
+import { findRecords, installAntigravity } from './adapters/install.mjs';
+
+export const TOOLS = [
+  { value: 'claude', label: 'Claude Code: the plugin, which updates itself and adds no files to the repository' },
+  { value: 'antigravity', label: 'Antigravity: the IDE, the App and the CLI, with a plugin rendered for them' }
+];
+export const INIT_SCOPES = ['project', 'machine'];
+
+/** Parses what follows `init`: { tools, scope, yes, force } or { error }. `user` is accepted for `machine`. */
+export function parseInitArgs(rest) {
+  const out = { command: 'init', tools: null, scope: null };
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    const take = (name) => (arg === name ? rest[++i] : arg.slice(name.length + 1));
+    if (arg === '--tools' || arg.startsWith('--tools=')) out.tools = String(take('--tools') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    else if (arg === '--scope' || arg.startsWith('--scope=')) out.scope = take('--scope');
+    else if (arg === '--yes' || arg === '-y') out.yes = true;
+    else if (arg === '--force') out.force = true;
+    else return { error: `unknown option "${arg}"` };
+  }
+  if (out.scope === 'user') out.scope = 'machine';
+  if (out.scope !== null && !INIT_SCOPES.includes(out.scope)) return { error: `the scope of init must be project or machine` };
+  if (out.tools) {
+    const unknown = out.tools.filter((t) => !TOOLS.some((x) => x.value === t));
+    if (unknown.length) return { error: `unknown tool "${unknown[0]}"; the tools are ${TOOLS.map((t) => t.value).join(', ')}` };
+    if (out.tools.length === 0) return { error: '--tools needs at least one tool' };
+  }
+  return out;
+}
+
+/** Like resolveScope of cli.mjs, with the choices project and machine. */
+export function resolveInitScope({ given = null, interactive = false, inRepo = false }) {
+  if (given) return { scope: given };
+  const preferred = inRepo ? 'project' : 'machine';
+  if (interactive) return { ask: true, preferred };
+  const why = inRepo ? 'this folder is inside a git repository, so the project is used' : 'this folder is not inside a git repository, so the machine is used';
+  return { scope: preferred, reason: `no --scope given and no terminal: ${why}` };
+}
+
+export function initScopeChoices({ cwd, inRepo }) {
+  return [
+    { value: 'project', label: `Project (${cwd})${inRepo ? '' : ' [not a git repository]'}: files in the repository, shared with your team` },
+    { value: 'machine', label: 'Machine: every project of this machine' }
+  ];
+}
+
+/** The top folder of the git repository of the current folder, or null. */
+export function repoRoot(run) {
+  const r = run('git', ['rev-parse', '--show-toplevel']);
+  return r.code === 0 && r.output.trim() ? r.output.trim() : null;
+}
+
+const NEXT_STEP = 'Next: /relevo:init (the skill) sets up the labels and the rules of the repository; it is a separate step from this command.';
+
+/** Sets up each tool, in order, and stops at the first failure. Returns { code, lines }. */
+export function runInit({ tools, scope, force = false }, deps) {
+  const lines = [];
+  for (const tool of tools) {
+    lines.push(`== ${TOOLS.find((t) => t.value === tool).label.split(':')[0]}`);
+    const r =
+      tool === 'claude'
+        ? execute({ command: 'install', scope: scope === 'machine' ? 'user' : 'project' }, deps)
+        : installAntigravity({ packageRoot: deps.packageRoot, scope, root: deps.root, home: deps.home, run: deps.run, has: deps.has, force });
+    lines.push(...r.lines);
+    if (r.code !== 0) return { code: r.code, lines };
+  }
+  lines.push(NEXT_STEP);
+  return { code: 0, lines };
+}
+
+/**
+ * Updates Claude Code as before and renders again the plugins that `init` made. With neither, it says what it always
+ * said. The code is the worst of the parts, and each part says what it did.
+ */
+export function runUpdate({ scope = null, force = false }, deps) {
+  const records = findRecords({ root: deps.root, home: deps.home });
+  if (records.length === 0) return execute({ command: 'update', scope }, deps);
+  const lines = [];
+  let code = 0;
+  if (deps.has('claude')) {
+    lines.push('== Claude Code');
+    const r = execute({ command: 'update', scope }, deps);
+    lines.push(...r.lines);
+    code = r.code;
+  }
+  for (const rec of records) {
+    lines.push(`== Antigravity (${rec.scope})`);
+    const r = installAntigravity({ packageRoot: deps.packageRoot, scope: rec.scope, root: deps.root, home: deps.home, run: deps.run, has: deps.has, force, update: true });
+    lines.push(...r.lines);
+    code = code || r.code;
+  }
+  return { code, lines };
+}

package/scripts/lib/init.mjs

@@ -8,12 +8,14 @@
 import { loadConfig } from './config.mjs';
 import { LEGACY_PLATFORMS } from './platforms.mjs';
 import { labelDefinitions } from './labels.mjs';
+import { agentWorkflow } from './agent-workflow.mjs';
 import { OPENSPEC_INSTALL, REQUIRED_SKILLS, SKILL_INSTALL, WORKFLOW_FILES } from './doctor.mjs';
 
 export const REVIEW_MODES = ['none', 'peer', 'roles'];
 
 export const RUNS = ['cloud', 'local', 'both'];
 export const CREDENTIALS = ['api_key', 'subscription'];
+export const AGENT_BUILDS = ['claude', 'antigravity'];
 const API_KEY_LINE = '          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}';
 const TOKEN_LINE = '          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}';
 
@@ -22,6 +24,10 @@ const TOKEN_LINE = '          # claude_code_oauth_token: ${{ secrets.CLAUDE_CODE
  * subscription token that line is commented out and the token line is switched on. Throws when the template no
  * longer has the lines (a test runs this on the real template).
  */
+// The two official commands that install the plugin at the project scope; the person confirms this exact line.
+export const PLUGIN_PROJECT_COMMAND = 'claude plugin marketplace add elalfner/relevo --scope project --sparse .claude-plugin && claude plugin install relevo@relevo --scope project';
+const PLUGIN_PROJECT_DETAIL = 'It writes the marketplace and the enabled plugin into .claude/settings.json of this repository. It works even if the plugin is already installed for your machine, and nothing is committed for you.';
+
 export function credentialLine(workflow, credential) {
   if (credential !== 'subscription') return workflow;
   if (!workflow.includes(API_KEY_LINE) || !workflow.includes(TOKEN_LINE)) throw new Error('the go workflow template has no credential lines to switch');
@@ -83,7 +89,12 @@ export function renderConfig(template, answers = {}) {
   if (answers.specWriter !== undefined) out = set(out, 'spec_writer', answers.specWriter ?? 'null');
   if (answers.reviewMode) out = set(out, 'mode', answers.reviewMode);
   if (answers.merger) out = set(out, 'merger', answers.merger);
-  if (answers.runMaxCost !== undefined) out = set(out, 'run_max_cost', answers.runMaxCost);
+  if (answers.agentBuild === 'antigravity') {
+    // The agent has no cost limit: the limit of the run is a number of tokens, and the agent is named in its own group.
+    out = out.replace(/^(\s*)run_max_cost:[^\n]*$/m, '$1run_max_tokens: 2000000          # REQUIRED with agent.build antigravity: tokens per unattended run; choose your own');
+    out = `${out.trimEnd()}\n\n# Which agent builds in the cloud: claude (the default) or antigravity.\nagent:\n  build: antigravity\n`;
+    if (answers.runMaxTokens !== undefined) out = set(out, 'run_max_tokens', answers.runMaxTokens);
+  } else if (answers.runMaxCost !== undefined) out = set(out, 'run_max_cost', answers.runMaxCost);
   if (answers.language) out = set(out, 'language', answers.language);
   const check = loadConfig(out);
   if (!check.ok) throw new Error(`the answers produce an invalid relevo.yml: ${check.errors.map((e) => e.message).join('; ')}`);
@@ -174,6 +185,25 @@ export function planInit({ facts, answers, templates, current, admin }) {
   if (!facts.openspec) items.push(item('install.openspec', 'todo', 'Install the OpenSpec command-line tool', { install: true, command: 'npm install --global @fission-ai/openspec', detail: OPENSPEC_INSTALL }));
   REQUIRED_SKILLS.filter((n) => !facts.skills[n]).forEach((n) => items.push(item(`install.skill.${n}`, 'todo', `Install the ${n} skill`, { install: true, command: n === 'openspec-explore' ? 'openspec init' : 'npx skills add mattpocock/skills', detail: SKILL_INSTALL[n] })));
 
+  const configuredPlatforms = facts.config?.platforms ?? answers.platforms ?? (answers.platform ? { app: LEGACY_PLATFORMS[answers.platform] } : {});
+  const hasSupabase = Object.values(configuredPlatforms).some((p) => p?.stack === 'supabase');
+  if (hasSupabase) {
+    ['supabase', 'supabase-postgres-best-practices'].forEach((skill) => {
+      if (facts.skills?.[skill] === false) {
+        items.push(item(`install.skill.${skill}`, 'todo', `Install the ${skill} skill`, {
+          install: true,
+          command: `npx skills add supabase/agent-skills --skill ${skill}`,
+          detail: SKILL_INSTALL[skill] ?? `run \`npx skills add supabase/agent-skills --skill ${skill}\``,
+        }));
+      }
+    });
+  }
+
+  // the plugin, declared in the project so that a teammate who clones the repository is offered it
+  if (facts.pluginDeclared?.declared) items.push(item('install.plugin-project', 'ok', 'The repository declares the Relevo plugin (.claude/settings.json)'));
+  else if (facts.pluginDeclared?.unreadable) items.push(item('install.plugin-project', 'manual', '.claude/settings.json is not valid JSON: fix it, then run init again to declare the Relevo plugin in the project'));
+  else if (facts.pluginDeclared) items.push(item('install.plugin-project', 'todo', 'Declare the Relevo plugin in the project, so that a teammate who clones the repository is offered it (the new .claude/settings.json is left for you to commit)', { install: true, command: PLUGIN_PROJECT_COMMAND, detail: PLUGIN_PROJECT_DETAIL }));
+
   // relevo.yml
   if (facts.configText !== null) items.push(item('config', facts.config ? 'ok' : 'differs', facts.config ? 'relevo.yml exists and is valid' : `relevo.yml exists but is invalid: ${facts.configErrors.join('; ')}`));
   else items.push(item('config', 'todo', 'Create relevo.yml from the answers', { content: renderConfig(templates.config, { base, release, ...answers }) }));
@@ -216,10 +246,13 @@ export function planInit({ facts, answers, templates, current, admin }) {
   const credential = answers.credential ?? 'api_key';
   if (!RUNS.includes(runs)) throw new Error(`runs must be one of ${RUNS.join(', ')} (got "${runs}")`);
   if (!CREDENTIALS.includes(credential)) throw new Error(`credential must be one of ${CREDENTIALS.join(', ')} (got "${credential}")`);
+  const build = answers.agentBuild ?? 'claude';
+  if (!AGENT_BUILDS.includes(build)) throw new Error(`agentBuild must be one of ${AGENT_BUILDS.join(', ')} (got "${build}")`);
   const cloudFiles = ['relevo-go.yml', 'relevo-queue.yml'];
   WORKFLOW_FILES.forEach((file) => {
     if (runs === 'local' && cloudFiles.includes(file)) return;
-    const wanted = file === 'relevo-go.yml' ? credentialLine(templates.workflows[file], credential) : templates.workflows[file];
+    const shared = file === 'relevo-go.yml' ? credentialLine(templates.workflows[file], credential) : templates.workflows[file];
+    const wanted = agentWorkflow(shared, build, templates.agentBlocks);
     const have = current.workflows[file] ?? null;
     if (have === null) items.push(item(`workflow.${file}`, 'todo', `Add .github/workflows/${file}`, { path: `.github/workflows/${file}`, content: wanted }));
     else if (have === wanted) items.push(item(`workflow.${file}`, 'ok', `.github/workflows/${file} is up to date`));
@@ -253,6 +286,9 @@ export function planInit({ facts, answers, templates, current, admin }) {
     if ((facts.secrets ?? []).includes('RELEVO_LINKS_TOKEN')) items.push(item('manual.links-token', 'ok', 'The RELEVO_LINKS_TOKEN secret exists (init never reads it)'));
     else items.push(item('manual.links-token', 'manual', `If ${links.join(', ')} ${links.length > 1 ? 'are' : 'is'} private, create a fine-grained token with read access to issues and pull requests and store it yourself as the secret RELEVO_LINKS_TOKEN (init never reads or writes it; Relevo only reads with it, and public repositories need none)`));
   }
+  if (hasSupabase) {
+    items.push(item('manual.supabase-mcp', 'manual', 'To explore your Supabase database in Claude Code or Antigravity during /relevo:think, consider connecting the Supabase MCP server (see https://supabase.com/docs/guides/ai-tools)'));
+  }
   items.push(item('manual.push', 'manual', 'Commit and push the new files to the default branch: a workflow only runs from there'));
 
   return items;

package/scripts/lib/messages.mjs

@@ -17,6 +17,7 @@ const MAX_VALUE_LENGTH = 400;
 const REQUIRED = {
   built: ['assignee', 'issue', 'title', 'tasks_done', 'tasks_total', 'branch', 'scenarios'],
   qa_failed: ['assignee', 'issue', 'title', 'finding', 'branch'],
+  toolchain_missing: ['assignee', 'issue', 'title', 'tools', 'platform'],
   needs_spec: ['spec_writer', 'issue', 'title', 'missing'],
   changes_requested: ['author', 'issue', 'reviewer', 'summary'],
   needs_reviewer: ['spec_writer', 'issue', 'title', 'pr'],
@@ -38,6 +39,7 @@ const REQUIRED = {
 const STATE_OF = {
   built: 'built',
   qa_failed: 'qa-failed',
+  toolchain_missing: 'qa-failed',
   needs_spec: 'needs-spec',
   changes_requested: 'changes-requested',
   approved: 'pr-open',
@@ -67,6 +69,12 @@ const CATALOG = {
       'Full QA report: {{log_url}}',
       '{{next_line}}',
     ],
+    toolchain_missing: [
+      '@{{assignee}} #{{issue}} "{{title}}" was not built: the runner has no {{tools}} ❌',
+      '',
+      'What happened: the build job checked the toolchain of platform {{platform}} before the agent started, and {{tools}} is not on the path of the runner. Nothing was built and no model turns were spent.',
+      '{{next_line}}',
+    ],
     needs_spec: [
       '@{{spec_writer}} #{{issue}} "{{title}}" is back with you: the spec needs work',
       '',
@@ -173,6 +181,12 @@ const CATALOG = {
       'Reporte completo de QA: {{log_url}}',
       '{{next_line}}',
     ],
+    toolchain_missing: [
+      '@{{assignee}} #{{issue}} "{{title}}" no se construyó: el runner no tiene {{tools}} ❌',
+      '',
+      'Qué pasó: el job de build comprobó el toolchain de la plataforma {{platform}} antes de que empezara el agente, y {{tools}} no está en el path del runner. No se construyó nada y no se gastó ningún turno del modelo.',
+      '{{next_line}}',
+    ],
     needs_spec: [
       '@{{spec_writer}} #{{issue}} "{{title}}" regresa contigo: la spec necesita trabajo',
       '',
@@ -287,9 +301,10 @@ export function renderMessage(kind, data = {}, language = 'en') {
 
   // The next step comes from one table. needs-spec depends on why the issue came back, qa-failed on what the branch holds.
   if (STATE_OF[kind]) {
-    const reason = kind === 'needs_spec' ? values.reason ?? 'missing' : kind === 'qa_failed' ? values.recovery ?? (values.branch_state === 'kept' ? 'kept' : 'fix') : null;
+    const reason = kind === 'needs_spec' ? values.reason ?? 'missing' : kind === 'qa_failed' ? values.recovery ?? (values.branch_state === 'kept' ? 'kept' : 'fix') : kind === 'toolchain_missing' ? 'toolchain' : null;
     const step = nextStep({ state: STATE_OF[kind], reason, issue: values.issue, language: language_ });
     if (!present(values.command) && step.command) values.command = step.command;
+    if (kind === 'toolchain_missing') values.next_line = `${nextStepPrefix(language_)}: ${step.hint}.`;
     if (kind === 'needs_spec') values.next_line = `${nextStepPrefix(language_)}: ${step.command}: ${step.hint}.`;
     if (kind === 'qa_failed') {
       // For kept work the next step says what the command does and the other way forward; the others are the bare command.

package/scripts/lib/next-step.mjs

@@ -76,6 +76,15 @@ const TABLE = {
         es: 'verifica y corrige el trabajo que se guardó; para repensar el issue, usa /relevo:think y luego /relevo:issue {n}',
       },
     },
+    // Nothing was built: the runner lacks a tool of the profile, and the fix is in the workflow, not a command.
+    toolchain: {
+      command: null,
+      who: 'assignee',
+      hint: {
+        en: 'install the toolchain in the build job of relevo-go.yml (the template has the step for Flutter and Laravel, and /relevo:doctor checks it), then remove relevo:qa-failed and label the issue relevo:ready again',
+        es: 'instala el toolchain en el job de build de relevo-go.yml (la plantilla trae el paso para Flutter y Laravel, y /relevo:doctor lo comprueba), luego quita relevo:qa-failed y vuelve a poner relevo:ready al issue',
+      },
+    },
     'delete-branch': {
       command: null,
       who: 'assignee',
@@ -113,7 +122,7 @@ export const NEXT_STEP_STATES = Object.keys(TABLE);
 /** Reasons for the states whose next step depends on one. */
 export const NEXT_STEP_REASONS = {
   'needs-spec': ['missing', 'ambiguous'],
-  'qa-failed': ['fix', 'kept', 'delete-branch'],
+  'qa-failed': ['fix', 'kept', 'toolchain', 'delete-branch'],
 };
 
 const fill = (text, issue) => String(text).replaceAll('{n}', String(issue ?? ''));

package/scripts/lib/protected-paths.mjs

@@ -2,10 +2,15 @@
 //
 // Two tiers:
 //   hard  never allowed, whatever the issue says: workflows, the Relevo configuration, the folders of skills and
-//         the file with the project rules (a defect is fixed in the code, not by rewriting the rule).
+//         the file with the project rules (a defect is fixed in the code, not by rewriting the rule), and what carries
+//         the instructions or the permissions of another agent (`.agents/`, `.gemini/`, `AGENTS.md`, `GEMINI.md`):
+//         a run that could edit them could rewrite its own instructions.
 //   soft  dependency manifests and lock files: allowed only when the issue lists them in an `Allow-paths:` line.
 
-export const HARD_PATTERNS = ['.github/', 'relevo.yml', '.relevo/', '.claude/skills/', '.agents/skills/', 'skills-lock.json'];
+export const HARD_PATTERNS = ['.github/', 'relevo.yml', '.relevo/', '.claude/skills/', '.agents/', '.gemini/', 'skills-lock.json'];
+
+// Files that an agent reads from the folder of whatever it edits, so they are protected at any depth.
+export const HARD_ANY_DEPTH = ['AGENTS.md', 'GEMINI.md'];
 
 export const SOFT_FILES = [
   'pubspec.yaml', 'pubspec.lock',
@@ -60,7 +65,8 @@ const matchesHard = (path, pattern) => {
 
 /** The hard rule a path breaks, or null. */
 export function hardRule(path, { rulesFile = null } = {}) {
-  return hardPatterns(rulesFile).find((pattern) => matchesHard(path, pattern)) ?? null;
+  const name = clean(path).split('/').pop();
+  return hardPatterns(rulesFile).find((pattern) => matchesHard(path, pattern)) ?? HARD_ANY_DEPTH.find((f) => f === name) ?? null;
 }
 
 /** Is the file a dependency manifest or lock file (soft tier)? */
@@ -87,7 +93,7 @@ export function checkProtected(paths, { allow = [], rulesFile = null } = {}) {
 
 /** Entries of an `Allow-paths:` list that name (or would cover) a hard-protected path: they can never be allowed. */
 export function hardPathsInAllow(allow, { rulesFile = null } = {}) {
-  const probes = [...HARD_PATTERNS.map((pattern) => (pattern.endsWith('/') ? `${pattern}x` : pattern)), ...ruleFiles(rulesFile)].filter(Boolean);
+  const probes = [...HARD_PATTERNS.map((pattern) => (pattern.endsWith('/') ? `${pattern}x` : pattern)), ...HARD_ANY_DEPTH, ...ruleFiles(rulesFile)].filter(Boolean);
   return (allow ?? []).filter((entry) => hardRule(entry, { rulesFile }) || probes.some((probe) => matchesGlob(probe, entry)));
 }
 

package/scripts/lib/run-usage.mjs

@@ -57,7 +57,7 @@ export function usageLine(usage, { subscription = false } = {}) {
 // Messages the Claude CLI and the API document for a usage limit, a quota or an empty credit balance. These patterns
 // are not from a failed run seen here (see docs/pilot-findings.md); a wrong guess only changes the wording of a
 // comment on a run that already failed.
-const LIMIT_RE = /usage limit|limit reached|rate[ _-]?limit|credit balance is too low|exceeded your (current )?quota|insufficient[ _]quota/i;
+const LIMIT_RE = /usage limit|limit reached|rate[ _-]?limit|credit balance is too low|exceeded your (current )?quota|quota exceeded|resource[ _]exhausted|insufficient[ _]quota/i;
 
 /** Does the log show that a usage limit, a quota or the credit was reached? */
 export function reachedUsageLimit(text) {

package/scripts/lib/select.mjs

@@ -0,0 +1,118 @@
+// A list in the terminal that is chosen with the arrows, and nothing else: no dependency, so that the package stays
+// small. The input and the output are injected, so a test drives it with a simulated keyboard. The terminal is put
+// back (raw mode off, cursor shown) on every way out, including a cancel and an error.
+import { emitKeypressEvents } from 'node:readline';
+
+const HIDE = '\u001b[?25l';
+const SHOW = '\u001b[?25h';
+const UP = (n) => `\u001b[${n}A`;
+const CLEAR = '\u001b[0J';
+
+/**
+ * choices: [{ value, label }]; defaultIndex: the one selected at the start.
+ * Resolves the chosen value, or null when the person cancels (Esc, Ctrl-C, Ctrl-D, q).
+ * Keys: up/down (or k/j), Enter, the digits 1 to 9 as a shortcut that chooses at once.
+ */
+export function select({ title, choices, defaultIndex = 0, input, output, hint = 'Arrows and Enter to choose, a number to pick one, Esc to cancel' }) {
+  if (!input?.isTTY || typeof input.setRawMode !== 'function') return Promise.reject(new Error('the list needs a terminal'));
+  if (!Array.isArray(choices) || choices.length === 0) return Promise.reject(new Error('the list has no choices'));
+  return new Promise((resolve) => {
+    let index = Math.min(Math.max(defaultIndex, 0), choices.length - 1);
+    let drawn = 0;
+    const draw = () => {
+      const lines = [title, ...choices.map((c, i) => `${i === index ? '>' : ' '} ${i + 1}. ${c.label}`), hint];
+      output.write(`${drawn ? UP(drawn) : ''}\r${CLEAR}${lines.join('\n')}\n`);
+      drawn = lines.length;
+    };
+    const finish = (value) => {
+      input.removeListener('keypress', onKey);
+      try {
+        input.setRawMode(false);
+      } finally {
+        input.pause?.();
+        output.write(SHOW);
+      }
+      resolve(value);
+    };
+    function onKey(str, key = {}) {
+      try {
+        if (key.ctrl && (key.name === 'c' || key.name === 'd')) return finish(null);
+        if (key.name === 'escape' || str === 'q') return finish(null);
+        if (key.name === 'return' || key.name === 'enter') return finish(choices[index].value);
+        if (key.name === 'up' || str === 'k') index = (index + choices.length - 1) % choices.length;
+        else if (key.name === 'down' || str === 'j') index = (index + 1) % choices.length;
+        else if (/^[1-9]$/.test(str ?? '') && Number(str) <= choices.length) return finish(choices[Number(str) - 1].value);
+        else return undefined;
+        draw();
+      } catch (err) {
+        finish(null);
+        throw err;
+      }
+      return undefined;
+    }
+    emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume?.();
+    input.on('keypress', onKey);
+    output.write(HIDE);
+    draw();
+  });
+}
+
+/**
+ * Like `select`, but several choices can be ticked: Space (or the digit of a choice) toggles, Enter confirms.
+ * choices: [{ value, label }]; initial: the values ticked at the start. Resolves the array of ticked values in the
+ * order of `choices` (possibly empty), or null when the person cancels.
+ */
+export function selectMany({ title, choices, initial = [], input, output, hint = 'Arrows to move, Space or a number to tick, Enter to confirm, Esc to cancel' }) {
+  if (!input?.isTTY || typeof input.setRawMode !== 'function') return Promise.reject(new Error('the list needs a terminal'));
+  if (!Array.isArray(choices) || choices.length === 0) return Promise.reject(new Error('the list has no choices'));
+  return new Promise((resolve) => {
+    const ticked = new Set(initial);
+    let index = 0;
+    let drawn = 0;
+    const draw = () => {
+      const lines = [title, ...choices.map((c, i) => `${i === index ? '>' : ' '} [${ticked.has(c.value) ? 'x' : ' '}] ${i + 1}. ${c.label}`), hint];
+      output.write(`${drawn ? UP(drawn) : ''}\r${CLEAR}${lines.join('\n')}\n`);
+      drawn = lines.length;
+    };
+    const finish = (value) => {
+      input.removeListener('keypress', onKey);
+      try {
+        input.setRawMode(false);
+      } finally {
+        input.pause?.();
+        output.write(SHOW);
+      }
+      resolve(value);
+    };
+    const toggle = (i) => {
+      const v = choices[i].value;
+      if (ticked.has(v)) ticked.delete(v);
+      else ticked.add(v);
+    };
+    function onKey(str, key = {}) {
+      try {
+        if (key.ctrl && (key.name === 'c' || key.name === 'd')) return finish(null);
+        if (key.name === 'escape' || str === 'q') return finish(null);
+        if (key.name === 'return' || key.name === 'enter') return finish(choices.map((c) => c.value).filter((v) => ticked.has(v)));
+        if (key.name === 'up' || str === 'k') index = (index + choices.length - 1) % choices.length;
+        else if (key.name === 'down' || str === 'j') index = (index + 1) % choices.length;
+        else if (key.name === 'space' || str === ' ') toggle(index);
+        else if (/^[1-9]$/.test(str ?? '') && Number(str) <= choices.length) toggle(Number(str) - 1);
+        else return undefined;
+        draw();
+      } catch (err) {
+        finish(null);
+        throw err;
+      }
+      return undefined;
+    }
+    emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.resume?.();
+    input.on('keypress', onKey);
+    output.write(HIDE);
+    draw();
+  });
+}

package/scripts/lib/status-data.mjs

@@ -8,7 +8,13 @@ import { cloudBuilds, CLOUD_VARIABLE } from './execution-mode.mjs';
 
 const paged = (gh, path) => JSON.parse(gh(['api', '--paginate', '--slurp', path])).flat();
 
+// The first line of an error, which is the reason a read failed.
+const reasonOf = (err) => String(err?.stderr ?? err?.message ?? err).trim().split('\n')[0];
+const notFound = (err) => /404|Not Found/i.test(String(err?.stderr ?? err?.message ?? err));
+
 export function gatherStatus({ gh, ghLinks = gh, repo, config }) {
+  // The reads that fail and are not an answer; the report lists them so that a partial report is not taken for a complete one.
+  const unread = [];
   const names = resolveLabelNames(config.labels);
   const byNumber = new Map();
   LABELS.forEach((l) => {
@@ -44,8 +50,9 @@ export function gatherStatus({ gh, ghLinks = gh, repo, config }) {
     let behind = 0;
     try {
       behind = JSON.parse(gh(['api', `repos/${repo}/compare/${pr.head.sha}...${pr.base.ref}`])).ahead_by ?? 0;
-    } catch {
+    } catch (err) {
       behind = 0;
+      unread.push({ what: 'compare', pr: pr.number, reason: reasonOf(err) });
     }
     prs.push({
       number: pr.number, issue, url: pr.html_url, author: pr.user.login,
@@ -54,7 +61,7 @@ export function gatherStatus({ gh, ghLinks = gh, repo, config }) {
       approved: approvedBy.length > 0, behind_by: behind,
     });
   });
-  return { issues: issues.map(({ body, ...rest }) => rest), prs, milestones, externalBlocks: readExternalBlocks({ ghLinks, issues, repo, config, names }), cloudBuilds: readCloudBuilds({ gh, repo }) };
+  return { issues: issues.map(({ body, ...rest }) => rest), prs, milestones, externalBlocks: readExternalBlocks({ ghLinks, issues, repo, config, names }), cloudBuilds: readCloudBuilds({ gh, repo, unread }), unread };
 }
 
 /**
@@ -90,20 +97,24 @@ function readExternalBlocks({ ghLinks, issues, repo, config, names }) {
  * is not `off`. When the workflow cannot be read the answer is `true` (the cautious one: no extra rows, no claim
  * that a person must build by hand).
  */
-function readCloudBuilds({ gh, repo }) {
+function readCloudBuilds({ gh, repo, unread = [] }) {
   let workflowPresent;
   try {
     gh(['api', `repos/${repo}/contents/.github/workflows/relevo-go.yml`]);
     workflowPresent = true;
   } catch (err) {
-    if (!/404|Not Found/i.test(String(err.stderr ?? err.message ?? err))) return true;
+    if (!notFound(err)) {
+      unread.push({ what: 'workflow', reason: reasonOf(err) });
+      return true;
+    }
     workflowPresent = false;
   }
   let variable = null;
   try {
     variable = JSON.parse(gh(['api', `repos/${repo}/actions/variables/${CLOUD_VARIABLE}`])).value ?? null;
-  } catch {
+  } catch (err) {
     variable = null;
+    if (!notFound(err)) unread.push({ what: 'variable', reason: reasonOf(err) });
   }
   return cloudBuilds({ workflowPresent, variable });
 }

package/scripts/lib/status.mjs

@@ -28,7 +28,7 @@ function stateOf(issue, names) {
   return order.find((k) => issue.labels.includes(names[k])) ?? null;
 }
 
-export function buildStatus({ config, issues, prs = [], milestones = [], externalBlocks = {}, cloudBuilds = true, me = null, now = new Date() }) {
+export function buildStatus({ config, issues, prs = [], milestones = [], externalBlocks = {}, cloudBuilds = true, unread = [], me = null, now = new Date() }) {
   const names = resolveLabelNames(config.labels);
   const entries = issues.map((i) => ({
     number: i.number, title: i.title, state: stateOf(i, names), assignee: i.assignees[0] ?? null, milestone: i.milestone ?? null,
@@ -116,14 +116,19 @@ export function buildStatus({ config, issues, prs = [], milestones = [], externa
   return {
     me, view: isSpecWriter ? 'spec-writer' : 'person',
     onMe, toReview, toShip, readyForMe, waitingOnOthers, specWriter: specWriterView,
-    milestones: summaries, alerts, waiting,
+    milestones: summaries, alerts, waiting, unread,
     readOnly: true,
   };
 }
 
 const T = {
   en: {
-    nothing: 'Nothing is waiting on you.', onMe: 'Waiting on you', review: 'Pull requests to review', ship: 'Approved, ready to ship',
+    nothing: 'Nothing is waiting on you.', fromRead: '(from what could be read)', unreadTitle: 'Could not read, so this report may be incomplete',
+    unread: {
+      variable: (u) => `the variable RELEVO_CLOUD_GO (${u.reason}): the issues you could build by hand may be missing`,
+      workflow: (u) => `the workflow relevo-go.yml (${u.reason}): the cloud is assumed to build, so the issues you could build by hand may be missing`,
+      compare: (u) => `the comparison of the branch of pull request #${u.pr} with the base (${u.reason}): a branch that is behind may not be reported`,
+    }, onMe: 'Waiting on you', review: 'Pull requests to review', ship: 'Approved, ready to ship',
     others: 'Waiting on others', spec: 'Back with the spec writer', blocked: 'Blocked', needsReviewer: 'Need a reviewer', milestone: 'Milestone',
     noDue: 'has no due date, so no capacity warning is computed', merged: 'merged', inReview: 'in review', queued: 'queued', warn: 'capacity warning: more work than the team can review before the due date',
     alerts: 'Alerts', staleReview: 'review waiting', staleBranch: 'branch behind the base by',
@@ -131,7 +136,12 @@ const T = {
     readyForMe: 'Ready, for you to build (the cloud is not building)', stuck: 'build with no activity for', restart: 'remove relevo:building and apply relevo:ready again, or run',
   },
   es: {
-    nothing: 'Nada espera por ti.', onMe: 'Esperando por ti', review: 'Pull requests por revisar', ship: 'Aprobadas, listas para entregar',
+    nothing: 'Nada espera por ti.', fromRead: '(con lo que se pudo leer)', unreadTitle: 'No se pudo leer, así que este informe puede estar incompleto',
+    unread: {
+      variable: (u) => `la variable RELEVO_CLOUD_GO (${u.reason}): pueden faltar los issues que podrías construir a mano`,
+      workflow: (u) => `el workflow relevo-go.yml (${u.reason}): se supone que la nube construye, así que pueden faltar los issues que podrías construir a mano`,
+      compare: (u) => `la comparación de la rama del pull request #${u.pr} con la base (${u.reason}): puede que no se avise de una rama atrasada`,
+    }, onMe: 'Esperando por ti', review: 'Pull requests por revisar', ship: 'Aprobadas, listas para entregar',
     others: 'Esperando a otros', spec: 'De vuelta con quien escribe las specs', blocked: 'Bloqueadas', needsReviewer: 'Sin revisor', milestone: 'Milestone',
     noDue: 'no tiene fecha límite, así que no se calcula la advertencia de capacidad', merged: 'fusionadas', inReview: 'en revisión', queued: 'en cola', warn: 'advertencia de capacidad: hay más trabajo del que el equipo puede revisar antes de la fecha límite',
     alerts: 'Alertas', staleReview: 'revisión esperando', staleBranch: 'rama atrasada respecto a la base por',
@@ -160,7 +170,8 @@ export function renderStatus(report, language = 'en') {
   section(t.review, report.toReview.map((r) => `#${r.number} ${r.pr}`));
   section(t.ship, report.toShip.map((r) => `#${r.number} → ${r.command}`));
   section(t.others, report.waitingOnOthers.map((e) => withWaits(e, `#${e.number} ${e.title} (${e.state})`)));
-  if (!sw && !report.onMe.length && !report.toReview.length && !report.toShip.length) out.unshift(t.nothing, '');
+  const unread = report.unread ?? [];
+  if (!sw && !report.onMe.length && !report.toReview.length && !report.toShip.length) out.unshift(unread.length ? `${t.nothing} ${t.fromRead}` : t.nothing, '');
   report.milestones.forEach((m) => {
     out.push(`${t.milestone} "${m.title}": ${m.merged} ${t.merged}, ${m.inReview} ${t.inReview}, ${m.queued} ${t.queued}`);
     if (!m.dueOn) out.push(`  ${t.milestone} ${t.noDue}`);
@@ -173,6 +184,10 @@ export function renderStatus(report, language = 'en') {
       ? `#${a.issue} ${t.staleReview} ${a.hours}h (@${a.reviewer}) ${a.pr}`
       : `#${a.issue} ${t.staleBranch} ${a.behind} ${a.pr}`;
   }));
+  if (unread.length) {
+    if (out.length && out[out.length - 1] !== '') out.push('');
+    section(t.unreadTitle, unread.map((u) => t.unread[u.what](u)));
+  }
   while (out.length && out[out.length - 1] === '') out.pop();
   return out.join('\n');
 }