atris 3.82.2 → 3.82.4

package/commands/sentinel-powers.js

@@ -0,0 +1,284 @@
+'use strict';
+
+// The free sentinel commands: agents, guard, watch and flush. Each reports
+// to the dashboard through POST /api/sentinel/events (lib/sentinel-events.js).
+//
+//   atris sentinel agents [path] [--home]        check an agent setup
+//   atris sentinel guard install|uninstall|status|test [--global]
+//   atris sentinel watch [path] [--fix]          known attacks in dependencies
+//   atris sentinel flush                         send queued guard events
+//
+// An upload problem is a warning line. It never changes the exit code.
+
+const fs = require('fs');
+const path = require('path');
+
+function tildePath(p, home = require('os').homedir()) {
+  return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+}
+
+function parseFlags(argv, known) {
+  const opts = { paths: [] };
+  for (const a of argv) {
+    if (a.startsWith('--')) {
+      const name = a.slice(2);
+      if (!known.includes(name)) throw new Error(`unknown flag: ${a}`);
+      opts[name.replace(/-([a-z])/g, (_, c) => c.toUpperCase())] = true;
+    } else if (a.startsWith('-') && a !== '-') {
+      throw new Error(`unknown flag: ${a}`);
+    } else opts.paths.push(a);
+  }
+  return opts;
+}
+
+function resolveRoot(opts, deps) {
+  const root = path.resolve(opts.paths[0] || deps.root || process.cwd());
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`${root} is not a folder`);
+  return root;
+}
+
+function tokenFor(deps) {
+  if (deps.token !== undefined) return deps.token;
+  return require('../lib/sentinel-cloud').authToken();
+}
+
+function uploadLine(res, what) {
+  if (res.skipped === 'no-upload') return '  kept on this machine. nothing was sent (--no-upload)';
+  if (res.skipped === 'not-logged-in') return '  not logged in. nothing was sent. run atris login to see this on your dashboard';
+  if (!res.ok) return `  warning: could not send ${what} to your atris dashboard: ${res.reason}. the check itself is done`;
+  const resolved = res.resolved ? ` and marked ${res.resolved} as fixed` : '';
+  return `  sent ${res.sent - (res.resolved || 0)} ${what} to your atris dashboard${resolved}. no file contents or secret values were sent`;
+}
+
+// ---------------------------------------------------------------- agents
+
+async function runAgents(root, { home = false, upload = true, deps = {} } = {}) {
+  const agents = require('../lib/sentinel-agents');
+  const events = require('../lib/sentinel-events');
+  const homeDir = deps.homeDir || process.env.HOME || require('os').homedir();
+  const result = agents.runAgentCheck(root, { home, homeDir });
+  const evs = agents.toEvents(result, { repo: deps.repo });
+  let res;
+  try {
+    res = await events.reportFindings(root, 'agent_check', evs, { token: upload ? tokenFor(deps) : '', base: deps.base, env: deps.env || process.env, upload });
+  } catch (e) { res = { ok: false, reason: e.message }; }
+  return { result, events: evs, upload: res };
+}
+
+async function agentsCommand(argv, deps = {}) {
+  let opts;
+  try { opts = parseFlags(argv, ['home', 'json', 'no-upload']); } catch (e) { console.error(`  ${e.message}`); return 2; }
+  let root;
+  try { root = resolveRoot(opts, deps); } catch (e) { console.error(`  ${e.message}`); return 2; }
+  const { result, upload } = await runAgents(root, { home: Boolean(opts.home), upload: !opts.noUpload, deps });
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: result.grade !== 'fail', grade: result.grade, areas: result.areas, files: result.files, findings: result.findings, upload }, null, 2));
+  } else {
+    console.log(require('../lib/sentinel-agents').renderReport(result));
+    console.log(uploadLine(upload, 'the findings'));
+    console.log('');
+  }
+  return result.grade === 'fail' ? 1 : 0;
+}
+
+// ---------------------------------------------------------------- watch
+
+async function runWatchCheck(root, { upload = true, deps = {} } = {}) {
+  const watch = require('../lib/sentinel-watch');
+  const events = require('../lib/sentinel-events');
+  const result = await watch.runWatch(root, { base: deps.osvBase || process.env.ATRIS_OSV_BASE || watch.OSV_BASE, ...(deps.request ? { request: deps.request } : {}) });
+  const evs = watch.toEvents(result, { repo: deps.repo });
+  let res;
+  if (result.offline) res = { ok: true, skipped: 'offline', sent: 0 };
+  else {
+    try {
+      res = await events.reportFindings(root, 'threat', evs, { token: upload ? tokenFor(deps) : '', base: deps.base, env: deps.env || process.env, upload });
+    } catch (e) { res = { ok: false, reason: e.message }; }
+  }
+  return { result, events: evs, upload: res };
+}
+
+async function watchCommand(argv, deps = {}) {
+  let opts;
+  try { opts = parseFlags(argv, ['fix', 'json', 'no-upload']); } catch (e) { console.error(`  ${e.message}`); return 2; }
+  let root;
+  try { root = resolveRoot(opts, deps); } catch (e) { console.error(`  ${e.message}`); return 2; }
+  const watch = require('../lib/sentinel-watch');
+  const { result, upload } = await runWatchCheck(root, { upload: !opts.noUpload, deps });
+  let fix = null;
+  if (opts.fix && !result.offline && result.affected.length) {
+    try { fix = watch.applyFix(root, result, { log: (m) => console.error(`  ${m}`) }); } catch (e) { fix = { ok: false, reason: String(e.message || e).split('\n')[0] }; }
+  }
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: !result.affected.some((a) => a.severity === 'critical' || a.severity === 'high'), ...result, upload, fix }, null, 2));
+  } else {
+    console.log(watch.renderReport(result));
+    if (upload.skipped !== 'offline') console.log(uploadLine(upload, 'the threats'));
+    if (fix) {
+      console.log('');
+      if (!fix.ok) console.log(`  the fix did not run: ${fix.reason}`);
+      else if (!fix.branch) console.log(`  the fix changed nothing${fix.message ? `: ${fix.message}` : ''}`);
+      else {
+        console.log(`  updated ${fix.changed} file${fix.changed === 1 ? '' : 's'} on a new branch: ${fix.branch}`);
+        console.log(`  review it with: git diff ${fix.from || 'main'}...${fix.branch}`);
+        console.log(`  go back with: git checkout ${fix.from || 'main'}`);
+        console.log('  nothing was pushed');
+      }
+      if (fix.manual && fix.manual.length) {
+        console.log(`  update these yourself: ${fix.manual.map((a) => `${a.name} to ${a.fixed}`).join(', ')}`);
+      }
+    }
+    console.log('');
+  }
+  if (fix && !fix.ok) return 1;
+  return result.affected.some((a) => a.severity === 'critical' || a.severity === 'high') ? 1 : 0;
+}
+
+// ---------------------------------------------------------------- guard
+
+function guardHelp() {
+  console.log(`
+  atris sentinel guard, an action guard for coding agents
+
+    atris sentinel guard install            guard claude code in this project
+    atris sentinel guard install --global   guard every claude code session on this computer
+    atris sentinel guard status [--global]  is it on and what it stopped today
+    atris sentinel guard test               run sample commands through the rules
+    atris sentinel guard uninstall [--global]
+
+  it stops shell commands that send secrets out, delete home or root, force
+  push to main, drop databases or turn off security. normal curl, git push
+  and rm in project folders still run. it uses fixed rules and no model.
+  trusted sites for secrets can be added in ~/.atris/sentinel/guard.json.
+
+  what it promises: it stops the common ways an agent leaks a key or runs a
+  destructive command. a network call that carries a secret runs only through
+  curl, wget or httpie with options on a short safe list, to trusted sites. a
+  command that names claude settings or the guard's files runs only when it
+  is a read-only program like cat, grep or git log. what it cannot promise: a program that hides its
+  intent can still get past fixed rules. it does not read encoded payloads
+  or scripts written to disk and then run. it does not read interpreters
+  like python -c either. it is a seatbelt, not a sandbox.
+`);
+  return 0;
+}
+
+async function guardCommand(argv, deps = {}) {
+  const sub = argv[0] || 'status';
+  const rest = argv.slice(1);
+  if (sub === 'help' || argv.includes('--help') || argv.includes('-h')) return guardHelp();
+  let opts;
+  try { opts = parseFlags(rest, ['global', 'json']); } catch (e) { console.error(`  ${e.message}`); return 2; }
+  const inst = require('../lib/sentinel-guard-install');
+  const env = deps.env || process.env;
+  const root = deps.root || process.cwd();
+  const where = opts.global ? 'every claude code session on this computer' : `claude code in ${tildePath(path.resolve(root), env.HOME || undefined)}`;
+  if (sub === 'install') {
+    let st;
+    try { st = inst.install({ global: Boolean(opts.global), root, env, atrisBin: deps.atrisBin }); } catch (e) { console.error(`  could not install the guard: ${e.message}. your settings were not changed`); return 1; }
+    console.log(`\n  the sentinel guard is on for ${where}`);
+    console.log(`  settings: ${tildePath(st.settings, env.HOME || undefined)}`);
+    console.log('  it checks each shell command and file edit before it runs. try it with atris sentinel guard test');
+    if (st.hooks_off) console.log('  warning: these settings turn all hooks off. the guard will not run until that is removed');
+    console.log('  it starts with the next claude code session\n');
+    return 0;
+  }
+  if (sub === 'uninstall') {
+    try { inst.uninstall({ global: Boolean(opts.global), root, env }); } catch (e) { console.error(`  could not remove the guard: ${e.message}. your settings were not changed`); return 1; }
+    console.log(`  the sentinel guard is off for ${where}`);
+    return 0;
+  }
+  if (sub === 'status') {
+    const st = inst.status({ global: Boolean(opts.global), root, env });
+    const blocks = inst.recentBlocks({ env });
+    const events = require('../lib/sentinel-events');
+    const waiting = events.queueSize(env);
+    if (opts.json) { console.log(JSON.stringify({ ...st, blocked_today: blocks.length, waiting_to_send: waiting }, null, 2)); return 0; }
+    console.log('');
+    if (st.installed) console.log(`  the sentinel guard is on for ${where}`);
+    else if (!st.readable) console.log(`  could not read ${tildePath(st.settings, env.HOME || undefined)}. the guard state is unknown`);
+    else console.log(`  the sentinel guard is off for ${where}. turn it on with atris sentinel guard install${opts.global ? ' --global' : ''}`);
+    if (st.installed && !st.current) console.log('  the installed copy is older than this atris. run install again to update it');
+    if (st.hooks_off) console.log('  warning: these settings turn all hooks off. the guard does not run');
+    console.log(`  stopped ${blocks.length} action${blocks.length === 1 ? '' : 's'} in the last day${blocks.length ? `. latest: ${blocks[blocks.length - 1].reason.replace(/^blocked: /, '')}` : ''}`);
+    if (waiting) console.log(`  ${waiting} event${waiting === 1 ? '' : 's'} waiting to be sent to your dashboard`);
+    console.log('');
+    return 0;
+  }
+  if (sub === 'test') {
+    const guard = require('../lib/sentinel-guard');
+    const rows = guard.runSamples({ env });
+    if (opts.json) { console.log(JSON.stringify(rows, null, 2)); return rows.every((r) => r.ok) ? 0 : 1; }
+    console.log('\n  sample commands through the sentinel guard rules\n');
+    for (const r of rows) {
+      const mark = r.ok ? ' ' : '!';
+      console.log(`  ${mark} ${r.got === 'block' ? 'blocked' : 'allowed'}  ${r.command}`);
+      if (r.got === 'block') console.log(`             ${r.reason.replace(/^blocked: /, '')}`);
+    }
+    const bad = rows.filter((r) => !r.ok);
+    const blocked = rows.filter((r) => r.got === 'block').length;
+    console.log('');
+    console.log(`  ${blocked} of ${rows.length} samples blocked, ${rows.length - blocked} allowed`);
+    console.log(bad.length ? `  ${bad.length} sample${bad.length === 1 ? '' : 's'} did not do what was expected (marked !)` : '  every sample did what was expected');
+    console.log('');
+    return bad.length ? 1 : 0;
+  }
+  console.error(`  unknown guard command: ${sub}. use install, uninstall, status or test`);
+  return 2;
+}
+
+// ---------------------------------------------------------------- flush
+
+async function flushCommand(argv, deps = {}) {
+  const quiet = argv.includes('--quiet');
+  const events = require('../lib/sentinel-events');
+  const token = tokenFor(deps);
+  let res;
+  try { res = await events.flushQueue({ token, base: deps.base, env: deps.env || process.env }); } catch (e) { res = { ok: false, reason: e.message, sent: 0 }; }
+  if (!quiet) {
+    if (res.ok) console.log(`  sent ${res.sent} queued event${res.sent === 1 ? '' : 's'} to your atris dashboard`);
+    else console.log(`  warning: queued events were not sent: ${res.reason}. they stay queued for next time`);
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------- scheduled
+
+// What a scheduled run does before the paid review: the two free checks,
+// wrapped in scan_started and scan_finished events. Never throws.
+async function runScheduledFreeChecks(root, deps = {}) {
+  const events = require('../lib/sentinel-events');
+  const upload = deps.upload !== false;
+  const token = upload ? tokenFor(deps) : '';
+  const repo = events.repoName(root);
+  const started = new Date();
+  const say = deps.log || ((m) => console.log(m));
+  const out = { agents: null, watch: null, sent: [] };
+  const send = async (list) => {
+    if (!upload) return { ok: true, skipped: 'no-upload' };
+    if (!token) return { ok: false, reason: 'not logged in' };
+    try { return await events.postEvents(list, { token, base: deps.base }); } catch (e) { return { ok: false, reason: e.message }; }
+  };
+  const startEv = events.makeEvent({ kind: 'scan_started', repo, severity: 'info', title: 'Sentinel started its scheduled check of this project.', status: 'resolved', fingerprint: events.fingerprint('scan_started', repo, started.toISOString()), occurredAt: started });
+  out.sent.push(await send([startEv]));
+  try {
+    out.agents = await runAgents(root, { home: false, upload, deps: { ...deps, token } });
+    say(`  agent setup check: ${out.agents.result.grade}, ${out.agents.result.findings.length} finding${out.agents.result.findings.length === 1 ? '' : 's'}`);
+  } catch (e) { say(`  warning: the agent setup check did not finish: ${e.message}`); }
+  try {
+    out.watch = await runWatchCheck(root, { upload, deps: { ...deps, token } });
+    if (out.watch.result.offline) say('  warning: the dependency check could not reach the osv database this time');
+    else say(`  dependency check: ${out.watch.result.affected.length} affected package${out.watch.result.affected.length === 1 ? '' : 's'}`);
+  } catch (e) { say(`  warning: the dependency check did not finish: ${e.message}`); }
+  const agentsOpen = out.agents ? out.agents.result.findings.length : 0;
+  const threats = out.watch && !out.watch.result.offline ? out.watch.result.affected.length : 0;
+  const bad = (out.agents && out.agents.result.grade === 'fail') || (out.watch && out.watch.result.affected.some((a) => a.severity === 'critical' || a.severity === 'high'));
+  const title = events.fillPlain('Sentinel finished its scheduled check. {a} agent setup findings and {t} dependency threats are open.', { a: ['count', String(agentsOpen), 'some'], t: ['count', String(threats), 'some'] });
+  const finished = new Date();
+  const endEv = events.makeEvent({ kind: 'scan_finished', repo, severity: bad ? 'high' : 'info', title, status: 'resolved', fingerprint: events.fingerprint('scan_finished', repo, started.toISOString()), occurredAt: finished });
+  out.sent.push(await send([endEv]));
+  if (upload && token) { try { await events.flushQueue({ token, base: deps.base, env: deps.env || process.env }); } catch {} }
+  return out;
+}
+
+module.exports = { agentsCommand, guardCommand, watchCommand, flushCommand, runScheduledFreeChecks, runAgents, runWatchCheck };

package/commands/task.js

@@ -5963,6 +5963,9 @@ function isUninitializedTaskFolder(cwd = process.cwd()) {
 
 function cmdNext(args) {
   const root = process.cwd();
+  const { buildAgentNext, printAgentNext } = require('../lib/agent-next');
+  const agent = buildAgentNext({ root, args });
+  if (agent) return printAgentNext(agent, { asJson: wantsJson(args), alias: 'command' });
   // Empty folder talks like bare atris. Walk up like the task db so a
   // project subdir stays in the room; stop before inheriting /tmp.
   // A leftover projection with live tasks still names that work.
@@ -12244,7 +12247,7 @@ async function run(args) {
   // `task next --help` is a help request, not a run. Next can open
   // the task db or print the desk, so never list or claim just to show usage.
   if (sub === 'next' && argsWantHelp(raw.slice(1))) {
-    console.log('Usage: atris task next [--tag <tag>] [--create-next]');
+    console.log('Usage: atris task next [--tag <tag>] [--agent <member>|--human] [--create-next]');
     return;
   }
   // `task show --help` is a help request, not a run. Show can dump
@@ -12254,13 +12257,17 @@ async function run(args) {
     return;
   }
   const result = await runTaskCommand(raw);
-  const skipsRender = hasFlag(raw, '--dry-run');
+  const readOnlyAgentNext = sub === 'next' && require('../lib/agent-next').agentCaller(raw.slice(1));
+  const skipsRender = hasFlag(raw, '--dry-run') || readOnlyAgentNext;
   if (MUTATING_TASK_COMMANDS.has(sub) && !skipsRender) autoRenderTodoFromDb();
   return result;
 }
 
 module.exports = {
   run,
+  taskQueueScopeFromArgs,
+  normalizeTaskQueueScope,
+  filterTasksByScope,
   chooseTaskOwner,
   readTeamMembers,
   createTaskApiServer,

package/lib/agent-next.js

@@ -0,0 +1,255 @@
+'use strict';
+
+// A read-only recommendation. Existing task commands own every transition.
+const { readFlag } = require('./arg-parser');
+const { workerEnvMarker } = require('./task-core');
+const { autoJobForMember } = require('./member-engine');
+const { skipReason, heldForPerson, taskCheck } = require('./member-task-pick');
+const { buildNextWorkContext } = require('./next-work-context');
+const reviewIntegrity = require('./review-integrity');
+const fs = require('fs');
+
+const text = (value) => typeof value === 'string' ? value.trim() : '';
+const quote = (value) => /^[A-Za-z0-9_.:-]+$/.test(String(value))
+  ? String(value) : "'" + String(value).replace(/'/g, "'\\''") + "'";
+const identifier = (value) => typeof value === 'string' && /^[A-Za-z0-9_.:-]{1,120}$/.test(value) ? value : null;
+const ref = (task) => identifier(task?.display_id) || identifier(task?.id) || '';
+const certified = (task) => task?.review?.agent_certified === true || task?.metadata?.agent_certified === true;
+const ownerField = (value) => typeof value === 'string' && value.length <= 80 && !/[\u0000-\u001f]/.test(value) ? value || null : null;
+const knownStatus = (value) => ['open', 'claimed', 'review', 'done', 'failed', 'archived', 'blocked'].includes(value) ? value : null;
+const sourceKind = (value) => ['database', 'mixed', 'projection', 'none'].includes(value) ? value : 'none';
+
+function agentCaller(args = [], env = process.env) {
+  if (args.includes('--human')) return null;
+  const explicit = args.some((arg) => arg === '--agent' || arg.startsWith('--agent='));
+  if (!explicit && env.ATRIS_AGENT_PROOF_ONLY === '0') return null;
+  if (!explicit && !workerEnvMarker(env) && !text(env.ATRIS_AGENT_ID)) return null;
+  const named = text(readFlag(args, '--agent'));
+  const as = text(readFlag(args, '--as'));
+  const member = named || as || text(env.ATRIS_AGENT_ID) || 'builder';
+  const error = named && as && named !== as ? 'conflicting_owner'
+    : !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$/.test(member) ? 'invalid_owner' : null;
+  return { kind: 'agent', member, error };
+}
+
+function checkFor(task) {
+  const metadata = task?.metadata || {};
+  const command = text(metadata.verify) || text(metadata.proof_needed);
+  return {
+    command,
+    runnable: Boolean(command) && command.length <= 600
+      && taskCheck({ metadata: { verify: command } }).runnable,
+  };
+}
+
+function planningNeeds(task) {
+  const meta = task.metadata || {};
+  const needs = [];
+  if (!checkFor(task).runnable) needs.push('runnable_check');
+  if (!(text(meta.task_goal) || text(meta.goal_objective) || text(meta.objective) || text(meta.stage_goal))) needs.push('goal');
+  if (!(text(meta.exit_condition) || text(meta.done_looks_like))) needs.push('exit_condition');
+  if (!text(meta.first_move)) needs.push('first_move');
+  if (!(meta.planned_at || meta.stage_plan_recorded_at || meta.stage === 'plan' || meta.stage === 'do')) needs.push('recorded_plan');
+  return needs;
+}
+
+function recommendAgentWork({ tasks = [], member, job = 'build', taskSource = 'database', taskId = '', isAuthor = reviewIntegrity.isTaskAuthor } = {}) {
+  const pending = tasks.filter((task) => taskSource === 'database' && identifier(task?.id)
+      && task?.status === 'review' && certified(task))
+    .sort((a, b) => Number(b.updated_at || 0) - Number(a.updated_at || 0))
+    .slice(0, 5).map((task) => ({
+      task_id: task.id || null, reference: ref(task) || null,
+      reason: 'human_acceptance', human_only: true,
+      command: ref(task) ? 'atris task accept ' + quote(ref(task)) : null,
+    }));
+  const result = (task, action, reason, needs = []) => ({
+    task, action, reason, needs, human_pending: pending,
+  });
+  const bound = taskId ? tasks.find((task) => task.id === taskId || ref(task) === taskId) : null;
+  if (taskId && !bound) return result(null, 'blocked', 'The requested task is not in current workspace evidence.', ['current_task']);
+  if (bound && taskSource !== 'database') {
+    return result(bound, 'discover', 'Confirm the bound task state before relying on this snapshot.', ['authoritative_task_state']);
+  }
+  const rows = taskId ? [bound] : tasks;
+  const eligible = rows.filter((task) => {
+    if (!task || typeof task !== 'object') return false;
+    // An absent or unusable check still permits planning. It never permits
+    // claiming or executing; ownership and human holds remain unchanged.
+    const probe = { ...task, metadata: { ...task.metadata, verify: '' } };
+    return !skipReason(probe, job, { member, recoverClaimed: true });
+  }).sort((a, b) => Number(b.status === 'claimed') - Number(a.status === 'claimed')
+    || Number(Boolean(text(b.metadata?.assigned_to))) - Number(Boolean(text(a.metadata?.assigned_to)))
+    || Number(a.created_at || 0) - Number(b.created_at || 0)
+    || String(a.id || '').localeCompare(String(b.id || '')));
+  let selected = eligible[0] || null;
+  if (!selected && job === 'review') {
+    selected = rows.find((task) => task?.status === 'review' && !certified(task)
+      && !heldForPerson(task) && !isAuthor(task, member)) || null;
+    if (selected) {
+      if (taskSource !== 'database') return result(selected, 'discover', 'Confirm the current task state before reviewing this snapshot.', ['authoritative_task_state']);
+      return result(selected, 'review', 'An independent reviewer can check the finished work.');
+    }
+  }
+  if (!selected) {
+    if (bound) return result(bound, 'blocked', 'This member has no permitted step on the requested task. Inspect its current contract.', ['eligible_task']);
+    return result(null, 'discover', 'No eligible work is recorded. Inspect the goal and prior results before proposing one verifiable change.', ['eligible_task']);
+  }
+  if (taskSource !== 'database') {
+    return result(selected, 'discover', 'Confirm current task evidence before claiming or changing this snapshot.', ['authoritative_task_state']);
+  }
+  const needs = planningNeeds(selected);
+  if (needs.length) return result(selected, 'plan', 'Inspect this task and record its goal, exit, first move and runnable check before starting it.', needs);
+  return selected.status === 'claimed'
+    ? result(selected, 'continue', 'Continue the owned work and collect real proof before marking it ready.')
+    : result(selected, 'claim', 'This owned or matching task has a recorded plan and runnable check.');
+}
+
+function recommendationCommand(decision, member) {
+  if (decision.action === 'discover') return null;
+  const taskRef = ref(decision.task);
+  if (!taskRef) return null;
+  if (decision.action === 'claim') return 'atris task claim ' + quote(taskRef) + ' --as ' + quote(member);
+  if (decision.action === 'review') return 'atris task review-chat ' + quote(taskRef) + ' --as ' + quote(member);
+  return 'atris task page ' + quote(taskRef) + ' --json';
+}
+
+function boundedPacket(payload) {
+  payload.output_budget = { max_bytes: 16000, limited: false };
+  // Include the longest alias, pretty formatting and the CLI newline.
+  const bytes = () => Buffer.byteLength(JSON.stringify({ ...payload, next_action: payload.command }, null, 2) + '\n');
+  const limited = () => {
+    payload.output_budget.limited = true;
+    if (Array.isArray(payload.context.gaps) && !payload.context.gaps.includes('response_budget_limited')) {
+      payload.context.gaps.push('response_budget_limited');
+    }
+  };
+  while (bytes() > 16000 && payload.human_pending.length > 1) {
+    payload.human_pending.pop();
+    limited();
+  }
+  for (const key of ['candidates', 'recent_outcomes', 'parts']) {
+    while (bytes() > 16000 && Array.isArray(payload.context[key]) && payload.context[key].length) {
+      payload.context[key].pop();
+      limited();
+    }
+  }
+  if (bytes() > 16000) {
+    limited();
+    payload.action = payload.action === 'blocked' ? 'blocked' : 'discover';
+    payload.command = null;
+    payload.scope = {};
+    payload.reason = 'The evidence exceeds the response budget. Inspect current sources before acting.';
+    payload.needs = [...new Set([...payload.needs, 'bounded_evidence'])];
+    payload.human_pending = [];
+    payload.context = {
+      schema: 'atris.next_work_context.v1', task_source: sourceKind(payload.context.task_source),
+      goal: null, parts: [], candidates: [], recent_outcomes: [], sources: [],
+      gaps: ['response_budget_limited'], next_step: { kind: 'discover', reason: payload.reason, check: null },
+    };
+  }
+  return payload;
+}
+
+function buildAgentNext({ root = process.cwd(), args = [], env = process.env, snapshot, tasks, scope = {}, evidence } = {}) {
+  const caller = agentCaller(args, env);
+  if (!caller) return null;
+  const taskDb = require('./task-db');
+  const workspaceRoot = taskDb.workspaceRoot(root);
+  const taskId = text(readFlag(args, '--task'));
+  const state = snapshot || require('./first-minute').loadLocalTaskState(workspaceRoot, {
+    includeAllActive: true, taskIds: taskId ? [taskId] : [],
+  });
+  const taskSource = sourceKind(state.source);
+  let rows = tasks || state.tasks;
+  let queryScope = scope;
+  if (!tasks && args.some((arg) => /^--(?:goal[-_]id|tag|status|review[-_]state)(?:=|$)/.test(arg))) {
+    // Reuse the task surface's existing filters, including goal/review scope.
+    // Loaded only for scoped calls, after command modules have initialized.
+    const { taskQueueScopeFromArgs, normalizeTaskQueueScope, filterTasksByScope } = require('../commands/task');
+    const queryArgs = args.flatMap((arg) => /^--[^=]+=/.test(arg)
+      ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg]);
+    queryScope = normalizeTaskQueueScope(taskQueueScopeFromArgs(queryArgs));
+    rows = filterTasksByScope(rows, queryScope);
+  }
+  const scopeFits = Buffer.byteLength(JSON.stringify(queryScope)) <= 2048;
+  const job = caller.error ? 'build' : autoJobForMember(caller.member, '');
+  let authorshipAvailable = true;
+  const isAuthor = job === 'review' && taskSource === 'database' ? (task, actor) => {
+    try {
+      if (!fs.existsSync(taskDb.getDbPath())) throw new Error('task history unavailable');
+      return taskDb.isAuthorOfTask(taskDb.open(), task, actor);
+    } catch {
+      authorshipAvailable = false;
+      return true; // Unknown authorship cannot establish an independent reviewer.
+    }
+  } : reviewIntegrity.isTaskAuthor;
+  const decision = caller.error
+    ? { task: null, action: 'blocked', reason: 'Name one valid functional owner for this agent.', needs: ['functional_owner'], human_pending: [] }
+    : !scopeFits ? { task: null, action: 'blocked', reason: 'Keep the requested scope small enough to inspect.', needs: ['bounded_scope'], human_pending: [] }
+    : recommendAgentWork({ tasks: rows, member: caller.member, job, taskSource, taskId, isAuthor });
+  if (!authorshipAvailable && decision.action !== 'review') {
+    decision.needs.push('authorship_history');
+    decision.reason = 'Confirm the task authorship history before assigning an independent review.';
+  }
+  if (decision.task && !identifier(decision.task.id)) {
+    decision.action = 'discover';
+    decision.needs.push('stable_task_identity');
+    decision.reason = 'Confirm a stable task identity before using this evidence.';
+  }
+  if (decision.task && [decision.task.claimed_by, decision.task.metadata?.assigned_to]
+    .some((value) => value != null && value !== '' && ownerField(value) === null)) {
+    decision.action = 'discover';
+    decision.needs.push('valid_task_ownership');
+    decision.reason = 'Confirm the recorded ownership before relying on this task evidence.';
+  }
+  if (decision.task && !knownStatus(decision.task.status)) {
+    decision.action = 'discover';
+    decision.needs.push('current_task_status');
+  }
+  const command = recommendationCommand(decision, caller.member);
+  const context = evidence || buildNextWorkContext({
+    root: workspaceRoot, tasks: rows, selected: decision.task, owner: caller.member,
+    taskSource, generatedAt: state.generated_at,
+  });
+  context.task_source = taskSource;
+  // The existing evidence packet keeps its own factual gaps. The action is
+  // the owner's next permitted step, not a claim that a check has passed.
+  context.next_step.kind = decision.action === 'plan' ? 'discover'
+    : ['claim', 'continue'].includes(decision.action) ? 'execute'
+    : decision.action === 'review' ? 'review' : decision.action === 'discover' ? 'discover'
+    : ['human_decision', 'wait'].includes(context.next_step.kind) ? context.next_step.kind : 'discover';
+  context.next_step.reason = decision.reason;
+  const task = decision.task;
+  return boundedPacket({
+    schema: 'atris.agent_next.v1', ok: !caller.error && scopeFits, status: decision.action === 'blocked' ? 'blocked' : 'ok',
+    actor: { kind: 'agent', member: caller.error ? null : caller.member },
+    owner: caller.error ? null : caller.member, action: decision.action,
+    task_id: identifier(task?.id), reference: task ? ref(task) || null : null,
+    command, reason: decision.reason, needs: decision.needs,
+    task: task ? {
+      id: identifier(task.id), display_id: identifier(task.display_id),
+      title: text(task.title).slice(0, 240), status: knownStatus(task.status),
+      claimed_by: ownerField(task.claimed_by), assigned_to: ownerField(task.metadata?.assigned_to),
+    } : null,
+    human_pending: decision.human_pending, context, scope: scopeFits ? queryScope : {},
+    safety: { read_only: true, claims_work: false, human_accept: false, awards_xp: false },
+  });
+}
+
+function printAgentNext(payload, { asJson = false, alias = 'next_action', log = console.log } = {}) {
+  if (asJson) {
+    log(JSON.stringify({ ...payload, [alias]: payload.command }, null, 2));
+    return 0;
+  }
+  const title = payload.task?.title;
+  const message = payload.action === 'plan' && title ? 'plan ' + title + ' and define its check.'
+    : payload.action === 'claim' && title ? title + ' has a plan and a check.'
+    : payload.action === 'continue' && title ? 'continue ' + title + '.'
+    : payload.reason;
+  log(message.replace(/^[A-Z]/, (letter) => letter.toLowerCase()));
+  if (payload.human_pending.length) log('\nhuman approval is still pending; this step does not accept that work.');
+  if (payload.command) log('\nnext: ' + payload.command);
+  return 0;
+}
+
+module.exports = { agentCaller, planningNeeds, recommendAgentWork, buildAgentNext, printAgentNext };

package/lib/campaign-keep.js

@@ -35,6 +35,7 @@ function cronSchedule(seconds) {
   if (minutes === 1) return '* * * * *';
   if (minutes < 60) return `*/${minutes} * * * *`;
   const hours = Math.round(minutes / 60);
+  if (hours >= 168) return '0 0 * * 0';
   return hours >= 24 ? '0 0 * * *' : `0 */${hours} * * *`;
 }
 

package/lib/first-minute.js

@@ -177,7 +177,7 @@ function titlesFromTodoSection(root, section) {
   }
 }
 
-function loadLocalTaskState(root = process.cwd(), { taskIds = [] } = {}) {
+function loadLocalTaskState(root = process.cwd(), { taskIds = [], includeAllActive = false } = {}) {
   let dbRows = [];
   let lookup = () => null;
   let databaseRead = false;
@@ -187,23 +187,30 @@ function loadLocalTaskState(root = process.cwd(), { taskIds = [] } = {}) {
     if (!fs.existsSync(taskDb.getDbPath())) throw new Error('no task db yet');
     const db = taskDb.open();
     const workspaceRoot = taskDb.workspaceRoot(root);
-    const rows = taskDb.listTasks(db, { workspaceRoot, limit: 200 });
+    // The visible window must not become a new numbering universe. Task
+    // commands resolve these references against the complete workspace.
+    const refRows = taskDb.listTasks(db, { workspaceRoot });
+    const rows = includeAllActive
+      ? refRows.filter((row) => ['open', 'claimed', 'review'].includes(row.status))
+      : taskDb.listTasks(db, { workspaceRoot, limit: 200 });
     // Busy queues must not crowd the last outcomes out of the handoff.
     const recent = ['done', 'failed'].flatMap((status) => taskDb.listTasks(db, { workspaceRoot, status, limit: 3, orderBy: 'updated_at' }));
     const seen = new Set(rows.map((row) => row.id));
     rows.push(...recent.filter((row) => !seen.has(row.id)));
-    if (Array.isArray(rows) && rows.length) dbRows = taskDb.withTaskDisplayRefs(rows);
+    if (Array.isArray(rows) && rows.length) dbRows = taskDb.withTaskDisplayRefs(rows, refRows);
     databaseRead = true;
     lookup = (id) => {
       const row = taskDb.getTask(db, id);
       // A foreign id in a damaged projection is not this workspace's work.
       if (row && !taskDb.rowInWorkspace(row, workspaceRoot)) return false;
-      return row ? taskDb.withTaskDisplayRefs([row])[0] : null;
+      return row ? taskDb.withTaskDisplayRefs([row], refRows)[0] : null;
     };
     // A shortlist is an output budget, not authority to invent a bound job.
     for (const id of taskIds.slice(0, 8)) {
-      if (dbRows.some((row) => row.id === id)) continue;
-      const row = lookup(id);
+      if (dbRows.some((row) => row.id === id || (includeAllActive && row.display_id === id))) continue;
+      const row = lookup(id) || (includeAllActive
+        ? taskDb.withTaskDisplayRefs(refRows, refRows).find((item) => item.display_id === id)
+        : null);
       if (row) dbRows.push(row);
     }
   } catch {