atris 3.60.0 → 3.62.0

package/lib/member-engine.js

@@ -26,6 +26,7 @@ const {
   rosterModelLabel,
   rosterPickFromValue,
 } = require('./engine-registry');
+const { isParkedText } = require('./member-park');
 
 const SEARCH_WORDS = Object.freeze(['navigator', 'researcher', 'research', 'search', 'scout']);
 const REVIEW_WORDS = Object.freeze(['validator', 'reviewer', 'review', 'judge', 'critic', 'verifier']);
@@ -211,8 +212,16 @@ function memberRosterEngine(memberName, root = process.cwd(), options = {}) {
   }
 }
 
+// A parked card stays on disk and still runs by name; this view (the roster
+// team block and the boot lineup) just leaves it out.
+function memberCardParked(root, name) {
+  const card = findMemberCard(root, name);
+  if (!card) return false;
+  try { return isParkedText(fs.readFileSync(card, 'utf8')); } catch { return false; }
+}
+
 // One row per member for `atris engine roster`, plus a warning for every
-// team line that could not be used.
+// team line that could not be used. Parked members are skipped.
 function teamRosterView(root = process.cwd(), options = {}) {
   const state = options.rosterState || readRosterState(root, options);
   const names = new Set(listTeamMembers(root));
@@ -223,6 +232,7 @@ function teamRosterView(root = process.cwd(), options = {}) {
       else if (layer.scope === 'project') warnings.push({ file: line.file, line: line.line, text: line.text, message: `there is no team member named ${line.member}, so the line does nothing` });
     }
   }
+  for (const name of [...names]) if (memberCardParked(root, name)) names.delete(name);
   const rows = [...names].sort().map((name) => {
     const picked = resolveEngineForMember(name, root, { ...options, rosterState: state });
     const line = teamLineFor(state, name);

package/lib/member-park.js

@@ -0,0 +1,138 @@
+'use strict';
+
+// A parked member keeps its folder and saved state; only the views skip it.
+// Parking is two frontmatter lines in MEMBER.md:
+//   status: parked
+//   parked_note: <date> <reason>
+// Views (`atris team`, the roster team block, the boot lineup, owner
+// inference) read isParked*. Nothing that runs a member reads it, so a
+// parked member still runs when called by name.
+
+const fs = require('fs');
+const path = require('path');
+
+const STATUS_LINE_RE = /^status:[ \t]*(['"]?)([^'"#\r\n]*?)\1[ \t]*(?:#.*)?$/m;
+const MEMBER_NAME_RE = /^[a-zA-Z0-9._-]+$/;
+
+function memberCardPath(root, name) {
+  return path.join(root, 'atris', 'team', name, 'MEMBER.md');
+}
+
+// Splits text into lines that keep their own endings, so a rewrite can
+// touch one line and leave every other byte, including mixed LF and CRLF,
+// exactly as written.
+function splitKeepEndings(text) {
+  return String(text || '').match(/[^\n]*\n|[^\n]+$/g) || [];
+}
+
+const lineBody = (line) => line.replace(/\r?\n$/, '');
+
+// The frontmatter is the lines between an opening "---" on the first line
+// and the next line that is exactly "---". An empty block is fine. Returns
+// { lines, open, close } as line indexes, or null when there is none.
+function frontmatterBlock(lines) {
+  if (!lines.length || lineBody(lines[0]).replace(/^\uFEFF/, '') !== '---') return null;
+  for (let at = 1; at < lines.length; at += 1) {
+    if (lineBody(lines[at]).trimEnd() === '---') return { open: 0, close: at };
+  }
+  return null;
+}
+
+function frontmatterStatus(text) {
+  const lines = splitKeepEndings(text);
+  const block = frontmatterBlock(lines);
+  if (!block) return '';
+  const inside = lines.slice(block.open + 1, block.close).map(lineBody).join('\n');
+  const match = STATUS_LINE_RE.exec(inside);
+  return match ? match[2].trim().toLowerCase() : '';
+}
+
+function isParkedText(text) {
+  return frontmatterStatus(text) === 'parked';
+}
+
+// For a frontmatter object already parsed by commands/member.js.
+function isParkedFrontmatter(frontmatter) {
+  return String((frontmatter && frontmatter.status) || '').trim().toLowerCase() === 'parked';
+}
+
+function isMemberParked(root, name) {
+  const key = String(name || '').trim();
+  if (!key || !MEMBER_NAME_RE.test(key)) return false;
+  try {
+    return isParkedText(fs.readFileSync(memberCardPath(root, key), 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+function todayStamp(now = new Date()) {
+  const date = now instanceof Date ? now : new Date(now);
+  const pad = (value) => String(value).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+function oneLine(text) {
+  return String(text || '').replace(/[\r\n]+/g, ' ').replace(/[–—]/g, '-').replace(/\s+/g, ' ').trim();
+}
+
+// Rewrites only the status and parked_note lines; every other byte of the
+// file stays as it was. Returns { ok, changed, message } or { ok: false, error }.
+function setMemberParked(root, name, { parked, note = '', now = new Date() } = {}) {
+  const key = String(name || '').trim();
+  if (!key || !MEMBER_NAME_RE.test(key)) {
+    return { ok: false, error: `no team member named ${key || '(blank)'}. see the team with: atris team --all` };
+  }
+  const file = memberCardPath(root, key);
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return { ok: false, error: `no team member named ${key}. see the team with: atris team --all` };
+  }
+  const already = isParkedText(text);
+  if (parked && already) return { ok: true, changed: false, message: `${key} is already parked` };
+  if (!parked && !already) return { ok: true, changed: false, message: `${key} is not parked` };
+
+  const lines = splitKeepEndings(text);
+  const block = frontmatterBlock(lines);
+  const endingOf = (line) => (/\r\n$/.test(line) ? '\r\n' : '\n');
+  let next;
+  if (parked) {
+    const reason = oneLine(note) || 'parked by hand';
+    const statusLine = 'status: parked';
+    const noteLine = `parked_note: ${todayStamp(now)} ${reason}; unpark with atris team unpark ${key}`;
+    if (!block) {
+      const eol = /\r\n/.test(text) ? '\r\n' : '\n';
+      next = `---${eol}name: ${key}${eol}${statusLine}${eol}${noteLine}${eol}---${eol}${text}`;
+    } else {
+      const inside = (at) => at > block.open && at < block.close;
+      const statusAt = lines.findIndex((line, at) => inside(at) && /^status:/.test(line));
+      const noteAt = lines.findIndex((line, at) => inside(at) && /^parked_note:/.test(line));
+      // A replaced line keeps its own ending; nothing else moves.
+      if (statusAt >= 0) lines[statusAt] = statusLine + endingOf(lines[statusAt]);
+      if (noteAt >= 0) lines[noteAt] = noteLine + endingOf(lines[noteAt]);
+      if (statusAt < 0 || noteAt < 0) {
+        const nameAt = lines.findIndex((line, at) => inside(at) && /^name:/.test(line));
+        const anchor = statusAt >= 0 ? statusAt : nameAt >= 0 ? nameAt : block.open;
+        const eol = endingOf(lines[anchor]);
+        const insert = [...(statusAt < 0 ? [statusLine + eol] : []), ...(noteAt < 0 ? [noteLine + eol] : [])];
+        lines.splice(anchor + 1, 0, ...insert);
+      }
+      next = lines.join('');
+    }
+  } else {
+    next = lines
+      .filter((line, at) => !(block && at > block.open && at < block.close && /^(status|parked_note):/.test(line)))
+      .join('');
+  }
+  fs.writeFileSync(file, next, 'utf8');
+  return { ok: true, changed: true, message: parked ? `parked ${key}` : `unparked ${key}` };
+}
+
+module.exports = {
+  isMemberParked,
+  isParkedFrontmatter,
+  isParkedText,
+  setMemberParked,
+};

package/lib/member-scaffold.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 const MEMBER_DIRS = Object.freeze(['skills', 'tools', 'context', 'logs']);
 
@@ -190,8 +191,44 @@ function memberBundlePresent(memberDir) {
   return true;
 }
 
+function updateMemberSkills(templateDir, memberDir) {
+  const sourceRoot = path.join(templateDir, 'skills');
+  if (!fs.existsSync(sourceRoot)) return [];
+  const targetRoot = path.join(memberDir, 'skills');
+  const updated = [];
+  const copySkills = (source, target, relative = '') => {
+    if (fs.existsSync(target) && !fs.lstatSync(target).isDirectory()) {
+      throw new Error(`Member skills path is not a directory: ${target}`);
+    }
+    fs.mkdirSync(target, { recursive: true });
+    for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+      const rel = path.join(relative, entry.name);
+      const sourceFile = path.join(source, entry.name);
+      const targetFile = path.join(target, entry.name);
+      if (entry.isDirectory()) {
+        copySkills(sourceFile, targetFile, rel);
+      } else if (entry.isFile()) {
+        const content = fs.readFileSync(sourceFile);
+        if (fs.existsSync(targetFile) && fs.lstatSync(targetFile).isFile()
+          && fs.readFileSync(targetFile).equals(content)) continue;
+        const temporary = path.join(target, `.${entry.name}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+        try {
+          fs.writeFileSync(temporary, content, { flag: 'wx' });
+          fs.renameSync(temporary, targetFile);
+        } finally {
+          fs.rmSync(temporary, { force: true });
+        }
+        updated.push(path.join('skills', rel));
+      }
+    }
+  };
+  copySkills(sourceRoot, targetRoot);
+  return updated;
+}
+
 module.exports = {
   ensureMemberBundle,
   memberBundlePresent,
   memberMarkdown,
+  updateMemberSkills,
 };

package/lib/roster-markdown.js

@@ -14,7 +14,7 @@
 //   build: claude opus 5.5, backup codex
 
 const OLD_ROSTER_NOTE = '> edit any time. each line is job: engine and model, an optional effort (low, medium, high, xhigh, max), then optional "backup <engine and model>", "max 20 min", and "until 2026-10-24" (the year is required).';
-const ROSTER_NOTE = '> edit any time. each "## job" lists its workers in order, one per line: "- tool, model: name", then optional "effort: medium", "max: 20 min", and "until 2026-10-24" (the year is required). the first ready worker leads and the rest back it up.';
+const ROSTER_NOTE = '> edit any time. each "## job" lists its workers in order, one per line: "- tool, model: name", then optional "effort: medium", "max: 20 min", "prep: search" (that job reads the task first and hands this worker a short brief), and "until 2026-10-24" (the year is required). the first ready worker leads and the rest back it up.';
 
 const ROSTER_MARKDOWN_TEMPLATE = [
   '# roster',

package/lib/roster-prep.js

@@ -0,0 +1,289 @@
+'use strict';
+
+// The prep pass. A heavy roster worker whose line says "prep: search" does
+// not explore on its own: before it runs, the search job's lead reads the
+// task read-only and writes a trimmed brief (file:line pointers, short
+// excerpts, the facts that matter). The heavy worker gets its normal prompt
+// plus that brief and one instruction: work from the brief. Heavy models
+// think; cheap ones gather.
+//
+// Prep is best effort. When it fails, stalls, or says nothing, the heavy
+// worker runs with its normal prompt and the record says why prep was
+// skipped. The prep pass records its own line in roster_runs.jsonl.
+
+const {
+  rosterJobKey,
+  rosterJobLabel,
+  resolveJobTeam,
+} = require('./engine-registry');
+const { spawnSync } = require('child_process');
+const { buildReadOnlyEngineInvocation, buildAskSpawnEnv, runAskProcess } = require('./engine-ask');
+const { appendRosterRun, parseRunUsage } = require('./roster-runs');
+
+// A brief is at most 300 lines and 20 KB: enough for a dozen file:line
+// pointers with short excerpts, small enough that a heavy model reads it in
+// one pass instead of exploring.
+const PREP_MAX_LINES = 300;
+const PREP_MAX_BYTES = 20 * 1024;
+// The prep worker's own time cap when its roster line sets none.
+const PREP_DEFAULT_SECONDS = 300;
+// How much of the heavy worker's own instructions the prep worker sees.
+const PREP_CONTEXT_LINES = 80;
+const PREP_CONTEXT_BYTES = 6 * 1024;
+const PREP_BLOCK_HEADING = '## brief from the prep pass';
+const PREP_CUT_NOTE = '(brief cut to fit its size cap)';
+
+function byteLength(text) {
+  return Buffer.byteLength(String(text || ''), 'utf8');
+}
+
+// Whole lines only, never more than maxLines lines or maxBytes bytes.
+function fitLines(lines, maxLines, maxBytes) {
+  const out = [];
+  let bytes = 0;
+  for (const line of lines.slice(0, maxLines)) {
+    const size = byteLength(line) + (out.length ? 1 : 0);
+    if (bytes + size > maxBytes) break;
+    out.push(line);
+    bytes += size;
+  }
+  return out;
+}
+
+// The prep worker's answer cut to the cap, note included. Empty when the
+// answer had nothing in it.
+function capBrief(raw) {
+  const text = String(raw || '').replace(/\r\n/g, '\n').trim();
+  if (!text) return { text: '', lines: 0, bytes: 0, cut: false };
+  const all = text.split('\n');
+  if (all.length <= PREP_MAX_LINES && byteLength(text) <= PREP_MAX_BYTES) {
+    return { text, lines: all.length, bytes: byteLength(text), cut: false };
+  }
+  const kept = fitLines(all, PREP_MAX_LINES - 1, PREP_MAX_BYTES - byteLength(PREP_CUT_NOTE) - 1);
+  while (kept.length && !kept[kept.length - 1].trim()) kept.pop();
+  const out = [...kept, PREP_CUT_NOTE].join('\n');
+  return { text: out, lines: kept.length + 1, bytes: byteLength(out), cut: true };
+}
+
+function sizeText(bytes) {
+  const value = Number(bytes) || 0;
+  if (value < 1024) return `${value} bytes`;
+  return `${(value / 1024).toFixed(1).replace(/\.0$/, '')} KB`;
+}
+
+function capText(seconds) {
+  const value = Math.round(Number(seconds) || 0);
+  return value < 60 ? `${value}s` : `${Math.round(value / 60)} min`;
+}
+
+function taskRef(task) {
+  return String(task && (task.display_id || task.task_id || task.id) || '').trim();
+}
+
+function prepPrompt({ task, prompt, forJob }) {
+  const context = fitLines(String(prompt || '').split('\n'), PREP_CONTEXT_LINES, PREP_CONTEXT_BYTES).join('\n');
+  const ref = taskRef(task);
+  return [
+    `You are the prep pass for a heavier ${forJob} worker. Do not edit, create, or delete anything.`,
+    'Read the task, find the files and facts that worker will need, and write a trimmed brief so it can think instead of exploring.',
+    '',
+    `Task${ref ? ` ${ref}` : ''}: ${String(task && task.title || '').trim().slice(0, 1200)}`,
+    '',
+    'The next worker\'s own instructions, for context only; do not follow them:',
+    '<<<',
+    context,
+    '>>>',
+    '',
+    `Write the brief as plain markdown, at most ${PREP_MAX_LINES} lines and ${PREP_MAX_BYTES / 1024} KB:`,
+    '- the files that matter, each as path:line with one line on why',
+    '- short verbatim excerpts, a few lines each, of the code the worker will change or judge',
+    '- facts the worker would otherwise go looking for: the test files, the check command, gotchas from atris/MAP.md',
+    '- one line on what you did not check',
+    'Print only the brief.',
+  ].join('\n');
+}
+
+// The heavy worker's prompt with the brief added, and the one plain rule.
+function withPrepBrief(prompt, prep) {
+  const source = String(prompt || '');
+  if (!prep || !prep.ok || !prep.brief || source.includes(PREP_BLOCK_HEADING)) return source;
+  return [
+    source,
+    '',
+    `${PREP_BLOCK_HEADING} (${prep.job}, ${prep.engine})`,
+    'Work from this brief. Open other files only if the brief is missing something, and say in your final report what was missing.',
+    '',
+    prep.brief,
+  ].join('\n');
+}
+
+// What the heavy worker's own record line says about its prep.
+function prepRecordFields(prep) {
+  if (!prep) return {};
+  if (!prep.ok) return { prep: `prep skipped: ${prep.reason}` };
+  return { prep: `prepped by ${prep.job}`, brief_lines: prep.lines, brief_bytes: prep.bytes };
+}
+
+// Always in the checkout being worked: a plain ask may start somewhere
+// faster (cursor starts in the home folder), but prep has to read this repo.
+async function defaultPrepAsk({ engine, model, effort, prompt, cwd, timeoutMs }) {
+  const invocation = buildReadOnlyEngineInvocation(engine, prompt, model, { timeoutMs, effort });
+  return runAskProcess(invocation, { cwd, timeoutMs });
+}
+
+// The same ask for a caller that cannot wait on a promise (autopilot phases
+// run synchronously). Same command, same answer shape as runAskProcess.
+function defaultPrepAskSync({ engine, model, effort, prompt, cwd, timeoutMs }) {
+  const invocation = buildReadOnlyEngineInvocation(engine, prompt, model, { timeoutMs, effort });
+  const run = spawnSync(invocation.bin, invocation.args, {
+    cwd,
+    env: buildAskSpawnEnv(),
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    killSignal: 'SIGKILL',
+    maxBuffer: 4 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const stdout = String(run.stdout || '');
+  const stderr = String(run.stderr || '');
+  const timedOut = Boolean(run.error && run.error.code === 'ETIMEDOUT');
+  const spawnError = run.error && !timedOut ? run.error : null;
+  const hasOutput = Boolean(stdout.trim() || stderr.trim());
+  let reason = 'ok';
+  if (timedOut) reason = 'timeout';
+  else if (spawnError) reason = 'spawn_error';
+  else if (run.status !== 0) reason = `exit_${run.status == null ? 'unknown' : run.status}`;
+  else if (!hasOutput) reason = 'no_output';
+  return { ok: reason === 'ok', reason, timed_out: timedOut, stdout, stderr: spawnError ? `${stderr}${spawnError.message}` : stderr };
+}
+
+function skipped(job, reason, extra = {}) {
+  return { ok: false, job, reason, brief: '', lines: 0, bytes: 0, ...extra };
+}
+
+// Who preps and with what, or { skip } when prep cannot run at all.
+function planPrepPass({ prepJob, forJob = 'build', task, prompt = '', worktreePath, root = process.cwd() }) {
+  const key = rosterJobKey(prepJob);
+  const label = key ? rosterJobLabel(key) : String(prepJob || '');
+  const forKey = rosterJobKey(forJob);
+  const forLabel = forKey ? rosterJobLabel(forKey) : String(forJob || 'build');
+  if (!key) return { skip: skipped(label, `"${prepJob}" is not a job`) };
+  if (key === forKey) return { skip: skipped(label, `${forLabel} cannot prep for itself`) };
+  let lead = null;
+  try {
+    lead = resolveJobTeam(key, root, { lowStakes: false }).lead;
+  } catch {
+    lead = null;
+  }
+  if (!lead) return { skip: skipped(label, `${label} has no ready worker`) };
+  const capSeconds = Number(lead.roster_max_seconds) > 0 ? Number(lead.roster_max_seconds) : PREP_DEFAULT_SECONDS;
+  return {
+    label,
+    forLabel,
+    lead,
+    engine: lead.id,
+    model: lead.roster_model || '',
+    capSeconds,
+    request: {
+      engine: lead.id,
+      model: lead.roster_model || '',
+      effort: lead.roster_effort || '',
+      prompt: prepPrompt({ task, prompt, forJob: forLabel }),
+      cwd: worktreePath || root,
+      timeoutMs: capSeconds * 1000,
+    },
+  };
+}
+
+// Judge the prep worker's answer, write its run line, and hand back the brief.
+function finishPrepPass(plan, answer, { startedMs, endedMs, task, root = process.cwd(), record = {} }) {
+  const { label, forLabel, lead, engine, model, capSeconds } = plan;
+  answer = answer || { ok: false, reason: 'no_answer', stdout: '' };
+  const brief = answer.ok && !answer.timed_out ? capBrief(answer.stdout) : capBrief('');
+  let outcome = 'landed';
+  let reason = '';
+  if (answer.timed_out) {
+    outcome = 'stalled';
+    reason = `stalled at ${capText(capSeconds)}`;
+  } else if (!answer.ok) {
+    outcome = 'failed';
+    const exit = /^exit_(\d+)$/.exec(String(answer.reason || ''));
+    reason = exit ? `${engine} exited ${exit[1]}`
+      : answer.reason === 'no_output' ? 'returned nothing'
+        : answer.reason === 'spawn_error' ? `${engine} could not start`
+          : `${engine} failed`;
+  } else if (!brief.text) {
+    outcome = 'failed';
+    reason = 'returned nothing';
+  }
+  appendRosterRun(root, {
+    at: new Date(startedMs).toISOString(),
+    job: label,
+    engine,
+    ...(model ? { model } : {}),
+    ...(lead.roster_effort ? { effort: lead.roster_effort } : {}),
+    max_seconds: capSeconds,
+    seconds: Math.max(0, (endedMs - startedMs) / 1000),
+    outcome,
+    detail: reason || `brief for ${forLabel}, ${brief.lines} lines, ${sizeText(brief.bytes)}`,
+    source: 'prep',
+    ...(taskRef(task) ? { task: taskRef(task) } : {}),
+    ...(record.member ? { member: record.member } : {}),
+    ...parseRunUsage({ stdout: answer.stdout, stderr: answer.stderr }),
+  });
+  if (reason) return skipped(label, reason, { engine });
+  return { ok: true, job: label, engine, brief: brief.text, lines: brief.lines, bytes: brief.bytes, cut: brief.cut };
+}
+
+function askFailure(error) {
+  return { ok: false, reason: 'runner_error', stderr: String(error && error.message || error), stdout: '' };
+}
+
+// One prep pass for one task. Never throws: every way it can go wrong comes
+// back as { ok: false, reason } so the heavy worker still runs.
+async function runPrepPass({
+  ask = defaultPrepAsk,
+  clock = Date.now,
+  record = {},
+  ...options
+} = {}) {
+  const plan = planPrepPass(options);
+  if (plan.skip) return plan.skip;
+  const startedMs = clock();
+  let answer;
+  try {
+    answer = await ask(plan.request);
+  } catch (error) {
+    answer = askFailure(error);
+  }
+  return finishPrepPass(plan, answer, { startedMs, endedMs: clock(), task: options.task, root: options.root, record });
+}
+
+// The same pass for a synchronous caller. The ask must answer synchronously.
+function runPrepPassSync({
+  ask = defaultPrepAskSync,
+  clock = Date.now,
+  record = {},
+  ...options
+} = {}) {
+  const plan = planPrepPass(options);
+  if (plan.skip) return plan.skip;
+  const startedMs = clock();
+  let answer;
+  try {
+    answer = ask(plan.request);
+  } catch (error) {
+    answer = askFailure(error);
+  }
+  return finishPrepPass(plan, answer, { startedMs, endedMs: clock(), task: options.task, root: options.root, record });
+}
+
+module.exports = {
+  PREP_MAX_LINES,
+  PREP_MAX_BYTES,
+  capBrief,
+  withPrepBrief,
+  prepRecordFields,
+  runPrepPass,
+  runPrepPassSync,
+};