ai-agentmanager 1.9.0 → 1.11.0

package/src/manager.js

@@ -47,6 +47,7 @@ const SUMMARIES = {
   humanai: { doc: 'humanai', run: 'runHumanAi' },
   diagrams: { doc: 'diagrams', run: 'runDiagrams' },
   walkthrough: { doc: 'walkthrough', run: 'runWalkthrough' },
+  scorecard: { doc: 'scorecard', run: 'runScorecard' },
 };
 /** Read / write where a summary of `kind` is kept on the agent record. */
 const getSummary = (agent, kind) => (SUMMARIES[kind].doc ? agent.docs?.[kind] : agent[SUMMARIES[kind].field]);
@@ -100,6 +101,8 @@ import { spawn } from 'node:child_process';
 import * as git from './git.js';
 import { parseDiff } from '../public/review.js';
 import { issueSummary, leadingIssue, wordsAfterLink } from './jira.js';
+import { combine, facts as scoreFacts, scorecardMarkdown, scorecardPrompt } from './scorecard.js';
+import { CONTAINER_ENGINES, claudeToken, containerName, containerRunning, engineMounts, gitCommonDir, removeContainer, runArgs, stopContainer } from './container.js';
 import { conflictMessage, findConflicts, related, repoKey, summarize as summarizeConflicts } from './conflicts.js';
 import { answerMessage, loadQuestions, questionsPath, questionsPrompt } from './inbox.js';
 import { STUCK_DEFAULTS, detectStuck } from './stuck.js';
@@ -592,6 +595,7 @@ export class AgentManager extends EventEmitter {
     startedBy,
     trigger,
     attachments,
+    isolation,
   }) {
     intent = (intent ?? '').trim();
     const staged = stagedFiles(attachments);
@@ -605,6 +609,12 @@ export class AgentManager extends EventEmitter {
     }
     // Planning while cloning moves the session between folders, which needs the engine's support.
     if (!engineDef.supports.planHandoff) plan = false;
+    // Isolation: "container" runs it in Docker (config "isolation": { "default": "container" } for all).
+    isolation = isolation === undefined ? this.config.isolation?.default ?? null : isolation || null;
+    if (isolation && isolation !== 'container') throw Object.assign(new Error('isolation is "container" or nothing'), { status: 400 });
+    if (isolation && !CONTAINER_ENGINES.has(engineId)) throw Object.assign(new Error(`${engineDef.label} can't run in a container yet (Claude Code and Codex can)`), { status: 400 });
+    // The session moves between folders mid-plan; a container is bound to one folder.
+    if (isolation) plan = false;
     const general = NO_REPO.has(kind);
     // A project shortcut (or name) fills in the repo / folder / base branch.
     const entry = !general && project ? this.resolveProject(project) : null;
@@ -637,6 +647,7 @@ export class AgentManager extends EventEmitter {
       priority: parsePriority(priority),
       ...(startedBy ? { startedBy } : {}),
       ...(trigger ? { trigger } : {}),
+      ...(isolation ? { isolation } : {}),
       name: name?.trim() || jiraKey || slug,
       slug,
       intent,
@@ -993,6 +1004,26 @@ export class AgentManager extends EventEmitter {
     return this.view(this.store.get(agent.id));
   }
 
+  /**
+   * `docker run` for an agent in a container (see container.js): its folder, its repository's git
+   * data, its brief and uploads, the engine's homes and sign-in; nothing else of this computer.
+   */
+  containerSpec(agent, engine, cwd, args) {
+    const name = containerName(agent.id);
+    removeContainer(name); // a leftover from a crash or a restart would block the name
+    const em = engineMounts(engine.id, cwd);
+    const real = (p) => (fs.existsSync(p) ? fs.realpathSync(p) : null);
+    const git = gitCommonDir(cwd);
+    // Plus any folders config.json adds ("isolation": { "mounts": [{ "host": "~/.npm", "readOnly": true }] }).
+    const extra = (this.config.isolation?.mounts ?? []).map((m) => ({ ...m, host: real(expandHome(m.host)) }));
+    const mounts = [...em.mounts, ...(git ? [{ host: git }] : []), { host: real(briefDir(agent.id)) }, { host: real(path.join(paths.uploads, agent.id)), readOnly: true }, ...extra].filter((m) => m.host);
+    const bin = this.config.isolation?.bin?.[engine.id] ?? em.bin;
+    const env = { ...this.childEnv(agent), ...(claudeToken() ? { CLAUDE_CODE_OAUTH_TOKEN: claudeToken() } : {}) };
+    // Variables passed in by name (values stay out of the command line): the engine's, plus config's "isolation.env".
+    const inner = ['TERM=xterm-256color', 'COLORTERM=truecolor', `AGENTMGR_AGENT_ID=${agent.id}`, 'AGENTMGR_TERMINAL=1', ...em.env, ...(this.config.isolation?.env ?? [])];
+    return { name, cmd: 'docker', env, args: runArgs({ agentId: agent.id, engineId: engine.id, cwd: fs.realpathSync(cwd), bin, args, config: this.config, mounts, env: inner }) };
+  }
+
   /** What every launch of this agent passes its engine: options, its brief folder, instructions. */
   launchOptions(agent, { planning = false } = {}) {
     const engine = engineOf(agent);
@@ -1096,19 +1127,23 @@ export class AgentManager extends EventEmitter {
       }
     }
 
-    if (!installed(engine, this.config)) {
+    // In a container the engine is inside the image, not on this computer.
+    const container = agent.isolation === 'container' && !NO_REPO.has(agent.kind);
+    if (!container && !installed(engine, this.config)) {
       const error = notInstalled(engine, this.config);
       this.patch(agent.id, { status: 'error', error });
       throw Object.assign(new Error(error), { status: 400 });
     }
     let proc;
     try {
-      proc = pty.spawn(engine.bin(this.config), args, {
+      const spec = container ? this.containerSpec(agent, engine, cwd, args) : { cmd: engine.bin(this.config), args, env: this.childEnv(agent) };
+      rt.container = spec.name ?? null;
+      proc = pty.spawn(spec.cmd, spec.args, {
         name: 'xterm-256color',
         cols: rt.cols,
         rows: rt.rows,
         cwd,
-        env: this.childEnv(agent),
+        env: spec.env,
       });
     } catch (err) {
       this.patch(agent.id, { status: 'error', error: `Failed to launch ${engine.bin(this.config)}: ${err.message}` });
@@ -1231,9 +1266,14 @@ export class AgentManager extends EventEmitter {
         done.dispose();
         resolve(this.view(this.store.get(agent.id) ?? agent));
       });
-      // A hangup, as when a terminal closes, unless the engine shuts down cleanly on another signal.
-      rt.pty.kill(engineOf(agent).stopSignal ?? 'SIGHUP');
-      rt.killTimer = setTimeout(() => rt.pty?.kill('SIGKILL'), timeoutMs);
+      // A container: docker stop (the engine gets SIGTERM inside; the docker command then ends).
+      // Otherwise a hangup, as when a terminal closes, unless the engine ends cleanly on another signal.
+      if (rt.container) stopContainer(rt.container, 10);
+      else rt.pty.kill(engineOf(agent).stopSignal ?? 'SIGHUP');
+      rt.killTimer = setTimeout(() => {
+        if (rt.container) removeContainer(rt.container);
+        rt.pty?.kill('SIGKILL');
+      }, timeoutMs);
     });
   }
 
@@ -1507,7 +1547,10 @@ export class AgentManager extends EventEmitter {
       rows: prev?.rows ?? 34,
     };
     if (rt.size) this.appendOutput(rt, '\r\n\x1b[2m── new shell ──\x1b[0m\r\n');
-    const proc = pty.spawn(this.config.shell, ['-l'], {
+    // An agent in a running container: the shell opens inside it, with what the agent sees.
+    const inside = agent.isolation === 'container' && containerRunning(containerName(agent.id));
+    const [cmd, cmdArgs] = inside ? ['docker', ['exec', '-it', '-w', fs.realpathSync(agent.workdir), containerName(agent.id), 'bash', '-l']] : [this.config.shell, ['-l']];
+    const proc = pty.spawn(cmd, cmdArgs, {
       name: 'xterm-256color',
       cols: rt.cols,
       rows: rt.rows,
@@ -1887,6 +1930,8 @@ export class AgentManager extends EventEmitter {
       this.patch(id, { brief });
       // The agent says it is done: have the judge check the work before the person looks.
       if (brief.status === 'done' && agent.brief?.status !== 'done' && this.judge.enabled) this.requestReview(id, { trigger: 'brief' }).catch(() => {});
+      // ...and score it for the reviewer ("scorecard": { "auto": false } in config.json turns this off).
+      if (brief.status === 'done' && agent.brief?.status !== 'done' && this.config.scorecard?.auto !== false && !NO_REPO.has(agent.kind) && this.changesSource) this.summarize(id, 'scorecard').catch(() => {});
     }
     if (agent.planReview) {
       const file = loadPlanFile(id, agent.planReview);
@@ -2136,6 +2181,42 @@ export class AgentManager extends EventEmitter {
     );
   }
 
+  /**
+   * The review scorecard (see scorecard.js): the same diff the review screen shows, scored against
+   * the intent, spec and plan, with the facts the app measures capping what the model says.
+   */
+  async runScorecard(agent, ctx) {
+    if (!this.changesSource) throw new Error('Changes are not available here');
+    const data = await this.changesSource(agent.id);
+    const { hunks, cut } = walkthroughHunks(parseDiff(data.diff), { maxChars: 50_000 });
+    if (!hunks.length) throw Object.assign(new Error('No changes to score yet'), { status: 400 });
+    const cur0 = this.store.get(agent.id) ?? agent;
+    const doc = (n) => readSpecDoc(agent.id, n)?.markdown ?? '';
+    const f = scoreFacts({ files: data.files, prs: Object.values(cur0.prs ?? {}), brief: cur0.brief, plan: doc('plan'), spec: doc('spec') });
+    const writer = this.writerFor(agent);
+    const prompt = scorecardPrompt({ ...ctx, briefMarkdown: this.briefFile(agent.id).markdown ?? '', intentDoc: doc('intent'), specDoc: doc('spec'), planDoc: doc('plan'), hunks, facts: f });
+    const sc = combine(parseJsonReply(await this.oneShot(agent, prompt, writer)), f, hunks);
+    const cur = this.store.get(agent.id);
+    if (!cur) return null;
+    return this.view(
+      this.patch(
+        agent.id,
+        summaryPatch(cur, 'scorecard', {
+          data: sc,
+          cut,
+          diffHash: hash(data.diff),
+          markdown: scorecardMarkdown(sc, cur.name),
+          writer: `${writer.engine.label}${writer.model ? ` (${writer.model})` : ''}`,
+          postedTo: cur.docs?.scorecard?.postedTo ?? null,
+          at: now(),
+          briefUpdatedAt: cur.brief?.updatedAt ?? null,
+          pending: false,
+          error: null,
+        }),
+      ),
+    );
+  }
+
   /** Diagrams only: the problem and its solution drawn from the documents already written and the live context. */
   async runDiagrams(agent, ctx) {
     const cur0 = this.store.get(agent.id) ?? agent;
@@ -2772,7 +2853,8 @@ export class AgentManager extends EventEmitter {
     const keys = { esc: '\x1b', enter: '\r', up: '\x1b[A', down: '\x1b[B' };
     const data = keys[key] ?? (/^\d$/.test(key) ? key : null);
     if (!data) throw Object.assign(new Error('Unsupported key'), { status: 400 });
-    this.write(agent.id, data);
+    // Menus that read a line (the ACP client's) take Enter after the choice.
+    this.write(agent.id, engineOf(agent).promptKeyEnter && key !== 'enter' ? `${data}\r` : data);
     return { ok: true };
   }
 

package/src/review.js

@@ -143,6 +143,32 @@ export class Review {
     };
   }
 
+  /**
+   * Post the review scorecard on the agent's open pull request as a comment, so approvers see it in
+   * GitHub. Posting again edits the last comment instead of adding another.
+   */
+  async postScorecard(ref) {
+    const agent = this.agentWithRepo(ref);
+    const sc = agent.docs?.scorecard;
+    if (!sc?.markdown) throw err(409, 'Score the changes first');
+    const pr = Object.values(agent.prs ?? {}).find((p) => p.state === 'OPEN');
+    if (!pr) throw err(409, 'No open pull request for this agent');
+    this.manager.plugins.check('agent.pr', { agent: this.manager.auditView(agent), title: 'scorecard comment', draft: false });
+    const opts = { cwd: agent.workdir, timeout: 60_000 };
+    const args = ['pr', 'comment', pr.url, '--body', sc.markdown];
+    const again = sc.postedTo === pr.url;
+    try {
+      await git.run(ghBin(), again ? [...args, '--edit-last'] : args, opts);
+    } catch (e) {
+      // The comment we edited may be gone; add a new one.
+      if (!again) throw err(502, `Posting the scorecard failed: ${e.message.replace(/^gh .*? failed: /, '')}`);
+      await git.run(ghBin(), args, opts);
+    }
+    const cur = this.manager.store.get(agent.id);
+    this.manager.patch(agent.id, { docs: { ...cur.docs, scorecard: { ...cur.docs.scorecard, postedTo: pr.url, postedAt: new Date().toISOString() } } });
+    return { url: pr.url, edited: again };
+  }
+
   /** Send the comments to the agent as one message (typed in when it is idle). */
   comment(ref, { comments = [], note = '' } = {}) {
     const agent = this.agentWithRepo(ref);
@@ -194,8 +220,14 @@ export class Review {
     }
     const args = ['pr', 'create', '--head', branch];
     if (target) args.push('--base', target);
-    // The description: your text (else the commits), then the intent, spec and plan.
-    const sections = prSections(agent.id);
+    // The description: your text (else the commits), the review scorecard, then the intent, spec and plan.
+    const sc = agent.docs?.scorecard;
+    let card = '';
+    if (sc?.markdown) {
+      const now = base ? hash(await git.fullDiff(dir, base.sha)) : null;
+      card = sc.diffHash && now && sc.diffHash !== now ? `${sc.markdown}\n\n<sub>Scored before the latest changes.</sub>` : sc.markdown;
+    }
+    const sections = [card, prSections(agent.id)].filter(Boolean).join('\n\n');
     if (String(title).trim() || sections) {
       const log = base ? await git.run('git', ['log', '--reverse', '--format=%s', `${base.sha}..HEAD`], opts).catch(() => '') : '';
       const subjects = log.split('\n').filter(Boolean);

package/src/scorecard.js

@@ -0,0 +1,189 @@
+// The review scorecard: an agent's changes scored against what was asked (intent), what done means
+// (spec), staying on task (scope), its plan, the tests and safety, with an overall readiness and the
+// few places a person should actually read. A model judges; facts the app measures (CI, test files,
+// plan ticks, the spec's criteria) cap and correct it, and the recommendation follows fixed rules,
+// so a confident-sounding model can't talk a change into "ready".
+
+export const DIMENSIONS = [
+  ['intent', 'Intent', 'Does it do what was asked?'],
+  ['spec', 'Spec', 'Are the acceptance criteria met?'],
+  ['tests', 'Tests', 'Is it verified: CI, tests for the changed code, checks run?'],
+  ['safety', 'Safety', 'Risky areas handled: security, data, migrations, dependencies, public APIs (higher is safer)'],
+  ['scope', 'Scope', 'Only what the task needs, in proportion?'],
+  ['plan', 'Plan', 'Done as planned, departures explained?'],
+];
+const WEIGHTS = { intent: 25, spec: 20, tests: 20, safety: 15, scope: 10, plan: 10 };
+const TEST_FILE = /(^|\/)(tests?|__tests__|spec|specs)\/|[._-](test|spec)\.[a-z]+$|_test\.go$|Test\.java$/i;
+
+/** Facts the app knows without a model: CI, test files touched, the agent's checks, plan and spec progress. */
+export function facts({ files = [], prs = [], brief = null, plan = '', spec = '' }) {
+  const paths = files.map((f) => f.path);
+  const tests = paths.filter((p) => TEST_FILE.test(p));
+  const code = paths.filter((p) => !TEST_FILE.test(p) && !/\.(md|txt|rst|adoc)$/i.test(p) && !/(^|\/)docs?\//i.test(p));
+  const open = prs.find((p) => p.state === 'OPEN') ?? prs[0];
+  const checks = brief?.checks ?? [];
+  const count = (st) => checks.filter((c) => c.state === st).length;
+  const steps = [...String(plan).matchAll(/^\s*[-*]\s+\[([ xX~!])\]/gm)].map((m) => m[1].toLowerCase());
+  const criteriaBlock = /^##\s*Acceptance criteria\s*$([\s\S]*?)(?=^##\s|(?![\s\S]))/im.exec(String(spec))?.[1] ?? '';
+  return {
+    files: paths.length,
+    added: files.reduce((s, f) => s + (f.added ?? 0), 0),
+    removed: files.reduce((s, f) => s + (f.removed ?? 0), 0),
+    testFiles: tests.length,
+    codeFiles: code.length,
+    ci: open?.checks?.state ?? null, // passed | failed | running | null (no PR or no checks)
+    ciFailed: open?.checks?.failed ?? [],
+    checks: { passed: count('passed'), failed: count('failed'), pending: count('pending') + count('running') },
+    plan: steps.length ? { steps: steps.length, done: steps.filter((s) => s === 'x').length } : null,
+    criteria: criteriaBlock.split('\n').filter((l) => /^\s*[-*\d]/.test(l) && /\w/.test(l)).length,
+    hasSpec: Boolean(String(spec).trim()),
+  };
+}
+
+const factLines = (f) =>
+  [
+    `files changed: ${f.files} (+${f.added} -${f.removed}); code files: ${f.codeFiles}; test files: ${f.testFiles}`,
+    `CI on the pull request: ${f.ci ?? 'no pull request or no checks yet'}${f.ciFailed.length ? ` (failing: ${f.ciFailed.join(', ')})` : ''}`,
+    `the agent's own checks (from its brief): ${f.checks.passed} passed, ${f.checks.failed} failed, ${f.checks.pending} pending`,
+    `plan: ${f.plan ? `${f.plan.done} of ${f.plan.steps} steps ticked` : 'no plan written'}`,
+    `spec: ${f.hasSpec ? `${f.criteria} acceptance criteria` : 'no spec written'}`,
+  ].join('\n');
+
+export function scorecardPrompt({ intent, status, digest, briefMarkdown, intentDoc, specDoc, planDoc, hunks, facts: f }) {
+  return [
+    "You score an AI coding agent's changes for a reviewer who wants to approve with confidence and read as little as possible.",
+    'Be skeptical: a claim without evidence in the diff, the tests or the checks counts as unverified. Base everything on the material below.',
+    '',
+    'Reply with one JSON object only:',
+    '{"summary": "<two sentences: what the change does and how sure you are>",',
+    ' "scores": {"intent": {"score": 0-100, "why": "<one sentence>"}, "scope": {...}, "plan": {...}, "tests": {...}, "safety": {...}},',
+    ' "criteria": [{"criterion": "<an acceptance criterion from the spec>", "status": "met|not_met|unverified", "evidence": "<where: file, test, check>"}],',
+    ' "look": [{"id": "H3", "reason": "<why a person should read this hunk>"}]}',
+    '',
+    'Scoring (100 is best; be calibrated, not generous):',
+    '- intent: how fully the change does what INTENT asks. Missing parts of the ask pull it down hard.',
+    '- scope: 100 when every change serves the task; lower for unrelated edits, drive-by refactors, or a change far larger than the task needs.',
+    '- plan: how closely the change follows PLAN (steps done, departures explained). Without a plan, judge whether the work is coherent.',
+    '- tests: whether the changed behavior is verified: tests added or updated for it, CI, checks the agent ran. Code changes with no tests and no passing checks score low.',
+    '- safety: 100 when nothing risky is touched or risks are handled; lower for security, auth, data loss, migrations, concurrency, money, new dependencies or public API changes without care.',
+    '- criteria: one entry per acceptance criterion in SPEC, in its order; leave the list empty if there is no spec.',
+    '- look: at most 5 hunks a person must read (the risky, subtle or unverified ones), most important first. Not the obvious ones.',
+    '',
+    '<facts_measured_by_the_app>',
+    factLines(f),
+    '</facts_measured_by_the_app>',
+    '<intent>',
+    intentDoc || intent || '(none)',
+    '</intent>',
+    '<spec>',
+    specDoc || '(no spec written)',
+    '</spec>',
+    '<plan>',
+    planDoc || '(no plan written)',
+    '</plan>',
+    '<agent_status>',
+    status,
+    '</agent_status>',
+    '<conversation>',
+    (digest || '(none)').slice(-12_000),
+    '</conversation>',
+    '<brief>',
+    briefMarkdown || '(none)',
+    '</brief>',
+    '<hunks>',
+    ...hunks.map((h) => `<hunk id="${h.id}" file="${h.file}">\n${h.head}\n${h.text}\n</hunk>`),
+    '</hunks>',
+  ].join('\n');
+}
+
+const clamp = (n) => Math.max(0, Math.min(100, Math.round(Number(n) || 0)));
+
+/**
+ * The scorecard from the model's reply and the facts: scores capped by what was measured, the spec
+ * score computed from the criteria, the overall weighted, and a recommendation by rule.
+ */
+export function combine(reply, f, hunks) {
+  const s = reply?.scores ?? {};
+  const score = (k) => (s[k] && Number.isFinite(Number(s[k].score)) ? { score: clamp(s[k].score), why: String(s[k].why ?? '').slice(0, 300), notes: [] } : null);
+  const out = { intent: score('intent'), scope: score('scope'), plan: score('plan'), tests: score('tests'), safety: score('safety'), spec: null };
+  const cap = (k, max, note) => {
+    if (out[k] && out[k].score > max) {
+      out[k].score = max;
+      out[k].notes.push(note);
+    }
+  };
+  // Tests: failing CI or failing checks, or code changed with nothing verifying it.
+  if (f.ci === 'failed') cap('tests', 30, `CI is failing${f.ciFailed.length ? ` (${f.ciFailed.join(', ')})` : ''}`);
+  if (f.checks.failed) cap('tests', 40, `${f.checks.failed} of the agent's checks failed`);
+  if (f.codeFiles && !f.testFiles && !f.checks.passed && f.ci !== 'passed') cap('tests', 45, 'code changed with no tests and no passing checks');
+  // Plan: bounded by the steps ticked.
+  if (f.plan && out.plan) cap('plan', Math.round(40 + (60 * f.plan.done) / f.plan.steps), `${f.plan.done} of ${f.plan.steps} plan steps ticked`);
+  if (!f.plan && out.plan) out.plan.notes.push('no plan written');
+  // Spec: computed from the criteria (met 1, unverified ½, not met 0); none without a spec.
+  const criteria = (Array.isArray(reply?.criteria) ? reply.criteria : [])
+    .filter((c) => c?.criterion)
+    .slice(0, 20)
+    .map((c) => ({ criterion: String(c.criterion).slice(0, 300), status: ['met', 'not_met', 'unverified'].includes(c.status) ? c.status : 'unverified', evidence: String(c.evidence ?? '').slice(0, 300) }));
+  // A spec with criteria the model didn't assess: they count as unverified, not as passed.
+  if (f.hasSpec && f.criteria && !criteria.length) out.spec = { score: 50, why: `${f.criteria} acceptance criteri${f.criteria === 1 ? 'on' : 'a'} not assessed`, notes: ['treated as unverified'] };
+  if (f.hasSpec && criteria.length) {
+    const pts = criteria.reduce((n, c) => n + (c.status === 'met' ? 1 : c.status === 'unverified' ? 0.5 : 0), 0);
+    const met = criteria.filter((c) => c.status === 'met').length;
+    out.spec = { score: clamp((100 * pts) / criteria.length), why: `${met} of ${criteria.length} acceptance criteri${criteria.length === 1 ? 'on' : 'a'} met${criteria.some((c) => c.status === 'not_met') ? ', some not met' : ''}`, notes: [] };
+  }
+  // Overall: weighted over the scores there are.
+  const have = Object.entries(WEIGHTS).filter(([k]) => out[k]);
+  const total = have.reduce((n, [, w]) => n + w, 0);
+  const overall = total ? Math.round(have.reduce((n, [k, w]) => n + out[k].score * w, 0) / total) : null;
+  const notMet = criteria.filter((c) => c.status === 'not_met');
+  const reasons = [];
+  if (f.ci === 'failed') reasons.push('CI is failing');
+  if (notMet.length) reasons.push(`${notMet.length} acceptance criteri${notMet.length === 1 ? 'on' : 'a'} not met`);
+  if (out.intent && out.intent.score < 50) reasons.push('it does not do enough of what was asked');
+  if (out.tests && out.tests.score < 40 && f.ci !== 'failed') reasons.push('it is barely verified');
+  let recommendation;
+  if (reasons.length) recommendation = 'not_ready';
+  else if (overall != null && overall >= 80 && (out.tests?.score ?? 0) >= 70 && (out.safety?.score ?? 100) >= 70 && (out.spec?.score ?? 100) >= 70 && f.ci !== 'running') recommendation = 'ready';
+  else recommendation = 'look';
+  // Where to look, mapped back to hunks.
+  const byId = new Map(hunks.map((h) => [h.id, h]));
+  const look = (Array.isArray(reply?.look) ? reply.look : [])
+    .map((l) => ({ h: byId.get(String(l?.id ?? '').trim()), reason: String(l?.reason ?? '').slice(0, 300) }))
+    .filter((l) => l.h)
+    .slice(0, 5)
+    .map(({ h, reason }) => ({ file: h.file, head: h.head, reason }));
+  return { summary: String(reply?.summary ?? '').slice(0, 600), overall, recommendation, reasons, scores: out, criteria, look, facts: f };
+}
+
+export const RECOMMENDATION = { ready: 'Ready to approve', look: 'Look at these first', not_ready: 'Not ready' };
+
+/** Markdown: for Copy / Download, the pull request's description and a PR comment. */
+export function scorecardMarkdown(sc, title = '') {
+  const bar = (n) => (n == null ? '—' : `${n}`);
+  const rows = DIMENSIONS.map(([k, label]) => {
+    const d = sc.scores[k];
+    return `| ${label} | ${bar(d?.score)} | ${d ? [d.why, ...d.notes].filter(Boolean).join('; ').replace(/\|/g, '/') : k === 'spec' ? 'no spec written' : '—'} |`;
+  });
+  const out = [
+    `### Review scorecard${title ? `: ${title}` : ''}`,
+    '',
+    `**${sc.overall ?? '—'}/100 · ${RECOMMENDATION[sc.recommendation]}**${sc.reasons.length ? ` (${sc.reasons.join('; ')})` : ''}`,
+    '',
+    sc.summary,
+    '',
+    '| Score | /100 | Why |',
+    '| --- | --- | --- |',
+    ...rows,
+  ];
+  if (sc.criteria.length) {
+    out.push('', '**Acceptance criteria**', '');
+    for (const c of sc.criteria) out.push(`- ${c.status === 'met' ? '✅' : c.status === 'not_met' ? '❌' : '❔'} ${c.criterion}${c.evidence ? ` (${c.evidence})` : ''}`);
+  }
+  if (sc.look.length) {
+    out.push('', '**Where to look**', '');
+    for (const l of sc.look) out.push(`- \`${l.file}\` \`${l.head.replace(/^(@@[^@]*@@).*/, '$1')}\`: ${l.reason}`);
+  }
+  const f = sc.facts;
+  out.push('', `<sub>Measured: ${f.files} files (+${f.added} −${f.removed}), ${f.testFiles} test files, CI ${f.ci ?? 'n/a'}, checks ${f.checks.passed}✓ ${f.checks.failed}✗${f.plan ? `, plan ${f.plan.done}/${f.plan.steps}` : ''}. Scored by AI Agent Manager.</sub>`);
+  return out.join('\n');
+}

package/src/server.js

@@ -25,7 +25,7 @@ import { Studio } from './studio.js';
 import { Memory } from './memory.js';
 import { doctor } from './doctor.js';
 import { Triggers, tokenMatches } from './triggers.js';
-import { listEngines, registerEngine } from './engines/index.js';
+import { listEngines, registerAcpEngines, registerEngine } from './engines/index.js';
 import { Plugins, pluginSpecs } from './plugins.js';
 import { HubLink, linkUrls } from './hublink.js';
 import { Notifier, isWorkflowUrl, loadNotify, publicNotify, saveNotify, sendSlack } from './notify.js';
@@ -34,6 +34,7 @@ import { LiveBrowser } from './livebrowser.js';
 import * as remote from './remote.js';
 import * as service from './service.js';
 import { jiraView, saveJira } from './jira.js';
+import { CONTAINER_ENGINES, buildImage, claudeToken, dockerStatus, isBuilding, saveSecrets } from './container.js';
 import { Store } from './store.js';
 import { about, latestRelease } from './about.js';
 
@@ -63,7 +64,7 @@ function isAllowedOrigin(origin, port) {
 const PUBLIC_REMOTE_API = new Set(['POST /api/login', 'GET /api/session']);
 // Updates are not here: a signed-in device (a phone) can install the newest release too. It only
 // ever installs an official release from where this copy came from (git tag or npm) and restarts.
-const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|service$|jira$|editors$|agents\/[\w-]+\/open-in$|shutdown$)/;
+const LOCAL_ONLY_API = /^\/api\/(remote(\/|$)|notify(\/|$)|hub(\/|$)|triggers(\/|$)|service$|jira$|isolation\/|editors$|agents\/[\w-]+\/open-in$|shutdown$)/;
 const HOOK_PATH = '/api/hooks/agents';
 const NO_REPO_KINDS = new Set(['general', 'assistant']);
 
@@ -73,6 +74,8 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   const store = new Store(paths.state);
   const plugins = await new Plugins({ log: (m) => console.log(`[agentmgr] ${m}`) }).load(pluginSpecs(config), { config, base: paths.home });
   for (const { def } of plugins.engines) registerEngine(def);
+  // ACP agents (Gemini CLI, OpenCode, Goose, … and config's "acp") become engines.
+  registerAcpEngines(config);
   const manager = new AgentManager({ store, config, plugins });
   const backlog = new Backlog({ manager, store, config });
   const races = new Races({ manager, store });
@@ -241,6 +244,7 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
     }),
   );
   api.get('/agents/:id/specs/:name', wrap((req) => manager.specDoc(req.params.id, req.params.name)));
+  api.post('/agents/:id/scorecard/post', wrap((req) => review.postScorecard(req.params.id)));
   api.post('/agents/:id/plan', wrap((req) => manager.startPlanning(req.params.id)));
   api.post('/agents/:id/plan/approve', wrap((req) => manager.approvePlan(req.params.id, req.body?.note)));
   api.post('/agents/:id/plan/changes', wrap((req) => manager.requestPlanChanges(req.params.id, req.body?.note)));
@@ -512,6 +516,28 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   api.get('/agents/:id/memory', wrap((req) => memory.read(req.params.id)));
   api.put('/agents/:id/memory', wrap((req) => memory.write(req.params.id, req.body?.text)));
   api.post('/agents/:id/learn', wrap((req) => memory.learn(req.params.id, req.body?.text, { by: req.headers['x-agentmgr-agent'] ? undefined : 'you' })));
+  // Isolation: Docker, the agent image, the Claude token for containers, and the default for new agents.
+  let buildError = null;
+  const isolationView = async () => ({ ...(await dockerStatus(config)), building: isBuilding(), buildError, hasClaudeToken: Boolean(claudeToken()), engines: [...CONTAINER_ENGINES], default: config.isolation?.default ?? null });
+  api.get('/isolation', wrap(isolationView));
+  api.post(
+    '/isolation/build',
+    wrap(async () => {
+      buildError = null;
+      buildImage(config).catch((err) => (buildError = err.message));
+      return isolationView();
+    }),
+  );
+  api.put('/isolation/token', wrap(async (req) => (saveSecrets({ claudeOauthToken: String(req.body?.token ?? '').trim() || null }), isolationView())));
+  api.put(
+    '/isolation/default',
+    wrap(async (req) => {
+      const value = req.body?.container ? 'container' : null;
+      config.isolation = { ...config.isolation, default: value };
+      saveConfig({ isolation: config.isolation });
+      return isolationView();
+    }),
+  );
   // Jira: the site and API token used to show an issue's summary for agents created from its link.
   api.get('/jira', wrap(() => jiraView()));
   api.put(
@@ -970,6 +996,14 @@ export async function startServer({ port = PORT, host = HOST } = {}) {
   }
   manager.refreshAll().catch(() => {});
   hubLink.start();
+  // A cloud runner joins its hub by itself on first start (AGENTMGR_HUB_URL and AGENTMGR_HUB_CODE: an
+  // invite, or the hub's runner token), and stays joined across restarts (the link is kept on disk).
+  if (process.env.AGENTMGR_HUB_URL && process.env.AGENTMGR_HUB_CODE && !hubLink.status().joined) {
+    hubLink
+      .join(process.env.AGENTMGR_HUB_URL, process.env.AGENTMGR_HUB_CODE, process.env.AGENTMGR_RUNNER_NAME || undefined)
+      .then((st) => console.log(`[agentmgr] joined the hub ${st.url} as ${st.name}`))
+      .catch((err) => console.error(`[agentmgr] could not join the hub ${process.env.AGENTMGR_HUB_URL}: ${err.message}`));
+  }
   return {
     hubLink,
     server,

package/src/trust.js

@@ -16,9 +16,8 @@ export function claudeConfigFile() {
  * before writing, only written when something changes, and replaced atomically.
  * Returns true if it changed anything.
  */
-export function trustFolder(dir) {
+export function trustFolder(dir, file = claudeConfigFile()) {
   const real = fs.realpathSync(dir);
-  const file = claudeConfigFile();
   let raw = '{}';
   try {
     raw = fs.readFileSync(file, 'utf8');