clembot-doorman 0.1.0

package/doorman/src/note.mjs

@@ -0,0 +1,213 @@
+/**
+ * The review note. One markdown file, one page, the human approval surface.
+ *
+ * ── Nothing auto-approves ────────────────────────────────────────────────────
+ *
+ * `status: pending` is the resting state and this module only ever writes that.
+ * A person flips it to `approved` or `denied` by editing the frontmatter, and
+ * the poller acts on the flip. Nothing here writes `approved`, ever.
+ *
+ * ── It never loses a report ──────────────────────────────────────────────────
+ *
+ * If the vault path is unset or unwritable the note goes to `registry/reviews/`
+ * with a warning. A review that vanished because a path was wrong is worse than
+ * a review in the wrong folder.
+ *
+ * ── It only ever creates and appends ─────────────────────────────────────────
+ *
+ * The vault belongs to the human. This writes new notes and appends to the
+ * decision log of notes it wrote. It never edits or deletes anything else.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { candidateSlug } from './candidate.mjs';
+
+/** A page. Same reasoning as the scorecard's report: enforced, not aspirational. */
+export const MAX_NOTE_LINES = 72;
+
+/** Where notes go inside the vault. */
+export const VAULT_SUBDIR = join('clembot-doorman', 'reviews');
+
+function yamlString(v) {
+  if (v === null || v === undefined) return 'null';
+  const s = String(v);
+  // Quote anything YAML would misread. A description with a colon in it is the
+  // common case and it silently truncates the value otherwise.
+  return /[:#\n"']/.test(s) ? JSON.stringify(s) : s;
+}
+
+/**
+ * Render the note.
+ *
+ * @param {object} r  a runVet result
+ * @returns {{ filename: string, body: string, truncated: boolean }}
+ */
+export function renderNote(r, { now = () => new Date() } = {}) {
+  const c = r.candidate;
+  const date = r.reviewed ?? now().toISOString().slice(0, 10);
+  const g = r.grade;
+
+  const front = [
+    '---',
+    `candidate: ${yamlString(c.id)}`,
+    `type: ${c.type}`,
+    `fit: ${r.fit ? r.fit.verdict : 'null'}`,
+    `owner: ${yamlString(r.fit && r.fit.owner)}`,
+    `grade: ${yamlString(g && g.grade)}`,
+    `cost_usdc: ${r.cost_usdc ?? 0}`,
+    `evidence_hash: ${yamlString(g && g.evidence_sha256)}`,
+    'status: pending',
+    `reviewed: ${date}`,
+    '---',
+    '',
+  ];
+
+  const head = [`# ${c.id}`, ''];
+
+  const tldr = ['## Verdict', ''];
+  if (r.fit) {
+    tldr.push(`**${r.fit.verdict}**. ${r.fit.rationale}`);
+    if (r.fit.verdict === 'fits' && r.fit.owner) {
+      tldr.push('', `Scoped to \`${r.fit.owner}\`.`);
+    }
+  } else {
+    tldr.push('No fit review ran.');
+  }
+  tldr.push('');
+
+  const overlap = ['## Overlap', ''];
+  if (r.fit && r.fit.overlaps.length) {
+    overlap.push('| Kind | Name | Already covers |', '|---|---|---|');
+    for (const o of r.fit.overlaps) overlap.push(`| ${o.kind} | \`${o.name}\` | ${o.why} |`);
+  } else {
+    overlap.push('Nothing in the current inventory covers this.');
+  }
+  overlap.push('');
+
+  const placement = ['## Placement', ''];
+  if (r.fit && r.fit.verdict === 'fits') {
+    placement.push(`\`${r.fit.owner}\` gets the tool. No other subagent is changed.`);
+    placement.push('');
+    placement.push('> Scoping here is **recorded, not enforced**. The gate matches every');
+    placement.push('> `mcp__*` call and reads only the tool name, so it cannot tell which');
+    placement.push('> subagent is calling. Treat `owner` as the intent, not a boundary.');
+  } else if (r.fit && r.fit.verdict === 'needs-new-subagent') {
+    placement.push('No existing subagent is the right home. A new one would have to be');
+    placement.push('created before this is worth adding.');
+  } else {
+    placement.push('Not placed: the fit review stopped before placement.');
+  }
+  placement.push('');
+
+  const scorecard = ['## Scorecard', ''];
+  if (g) {
+    scorecard.push(`**${g.grade} ${g.score}/100** against \`${g.model}\`.`);
+    const L = g.layers ?? {};
+    scorecard.push('', `Static ${fmt(L.static_pct)} · behavioural ${fmt(L.behavioral_pct)} · guidance ${fmt(L.guidance_pct)}`);
+    if (g.hard_fail) scorecard.push('', `**Hard fail:** ${g.hard_fail}`);
+    const worst = (g.grade_json && g.grade_json.worst_failure_modes) || [];
+    if (worst.length) {
+      scorecard.push('');
+      for (const w of worst.slice(0, 3)) scorecard.push(`- ${w}`);
+    }
+    if (r.transcripts) scorecard.push('', `[Replay the tape](${r.transcripts})`);
+  } else if (r.scan) {
+    scorecard.push('**behavioral grade: n/a - no tools to probe.**');
+    scorecard.push('', `Scanned ${r.scan.scanned_chars} chars of instruction text from \`${r.scan.source}\`${r.scan.truncated ? ' (TRUNCATED, so this is a partial scan)' : ''}.`);
+    scorecard.push('', r.scan.hits.length
+      ? `${r.scan.hard} hard, ${r.scan.steering} steering:`
+      : 'No pattern fired.');
+    for (const fmode of r.scan.failure_modes.slice(0, 4)) scorecard.push(`- ${fmode}`);
+  } else if (r.audit_id) {
+    scorecard.push('Queued, not yet graded. There is no grade here and no estimate of one.');
+    if (r.transcripts) scorecard.push('', `Tape (once it exists): ${r.transcripts}`);
+  } else {
+    scorecard.push('Not graded. The fit review stopped before the paid phase, which is');
+    scorecard.push('the point: a redundant candidate costs nothing.');
+  }
+  scorecard.push('');
+
+  const recipe = ['## Recipe', ''];
+  const recipeText = (g && g.recipe_md) || '';
+  if (recipeText) recipe.push(...recipeText.trim().split('\n'));
+  else recipe.push('_No recipe drafted._');
+  recipe.push('');
+
+  const log = [
+    '## Decision log', '',
+    `- ${date} · review written by the doorman · status \`pending\``,
+    '',
+  ];
+
+  // Trim the recipe FIRST, per the brief. It is the only section whose loss
+  // costs context rather than a claim.
+  let body = [...front, ...head, ...tldr, ...overlap, ...placement, ...scorecard, ...recipe, ...log];
+  let truncated = false;
+  while (body.length > MAX_NOTE_LINES && recipe.length > 3) {
+    recipe.splice(recipe.length - 2, 1);
+    truncated = true;
+    body = [...front, ...head, ...tldr, ...overlap, ...placement, ...scorecard, ...recipe, ...log];
+  }
+  if (truncated) {
+    recipe.splice(recipe.length - 1, 0, '', '_Recipe trimmed to hold one page. Full text is on the audit._');
+    body = [...front, ...head, ...tldr, ...overlap, ...placement, ...scorecard, ...recipe, ...log];
+  }
+
+  return {
+    filename: `${candidateSlug(c)}-${date}.md`,
+    body: body.join('\n').replace(/\n{3,}/g, '\n\n') + '\n',
+    truncated,
+  };
+}
+
+/**
+ * Write it. Vault first, registry fallback second, never nowhere.
+ *
+ * @returns {{ path: string, fellBack: boolean, warning: string|null }}
+ */
+export function writeNote(r, { vaultPath, registryDir, fs, now } = {}) {
+  const io = fs ?? { existsSync, mkdirSync, writeFileSync };
+  const { filename, body, truncated } = renderNote(r, { now });
+
+  const targets = [];
+  if (vaultPath) targets.push({ dir: join(vaultPath, VAULT_SUBDIR), vault: true });
+  if (registryDir) targets.push({ dir: join(registryDir, 'reviews'), vault: false });
+
+  let warning = null;
+  for (const t of targets) {
+    try {
+      io.mkdirSync(t.dir, { recursive: true });
+      const path = join(t.dir, filename);
+      io.writeFileSync(path, body, 'utf8');
+      return { path, fellBack: !t.vault, truncated, warning };
+    } catch (e) {
+      warning = `could not write to ${t.dir} (${e.message})`;
+      if (t.vault) {
+        warning += '; falling back to the registry so the report is not lost';
+      }
+    }
+  }
+  throw new Error('nowhere to write the review note. ' + (warning ?? 'no target given'));
+}
+
+/**
+ * Append one line to a note's decision log.
+ *
+ * The ONLY mutation this module makes to an existing file, and it is additive.
+ * A note whose log cannot be found is left alone and reported, rather than
+ * having a log section invented at the end of somebody's document.
+ */
+export function appendDecision(path, line, { fs } = {}) {
+  const io = fs ?? { readFileSync, appendFileSync };
+  const text = io.readFileSync(path, 'utf8');
+  if (!/^## Decision log$/m.test(text)) {
+    return { appended: false, reason: 'no "## Decision log" heading in that note' };
+  }
+  io.appendFileSync(path, `- ${line}\n`, 'utf8');
+  return { appended: true };
+}
+
+function fmt(v) {
+  return v === null || v === undefined ? '_not measured_' : `${v}%`;
+}

package/doorman/src/reviews.mjs

@@ -0,0 +1,120 @@
+/**
+ * Turning an approved note into a registry entry.
+ *
+ * Split out of the poller so it can be tested without a filesystem, a clock or
+ * a network. The poller reads notes and writes files; this decides what should
+ * happen, and decides nothing else.
+ *
+ * ── The rule that outranks the human ─────────────────────────────────────────
+ *
+ * A hard-failed server is refused even when the note says `approved`. Not
+ * because the human is wrong, but because "approved" on a note and "safe to put
+ * in the file the gate reads" are different claims, and a hard fail means the
+ * server was caught doing the one thing that disqualifies it outright. The
+ * refusal is written back into the note's decision log so it is visible where
+ * the decision was made, not buried in a terminal.
+ */
+
+import { parseFrontmatter } from './inventory.mjs';
+
+export const APPROVED = 'approved';
+export const DENIED = 'denied';
+export const PENDING = 'pending';
+
+/**
+ * Decide what a single note should cause.
+ *
+ * @param {object} note   { path, frontmatter }
+ * @param {object} registry { allow: {servers}, deny: {servers} }
+ * @returns {{ action, key, reason, entry? }}
+ *   action: 'allow' | 'deny' | 'refuse' | 'skip'
+ */
+export function decideForNote(note, registry = {}) {
+  const fm = note.frontmatter ?? {};
+  const status = (fm.status ?? '').trim();
+  const candidate = fm.candidate;
+  const key = fm.owner && fm.owner !== 'null' ? fm.owner : null;
+
+  if (status === PENDING || status === '') {
+    return { action: 'skip', reason: 'still pending; a human has not decided' };
+  }
+  if (status === DENIED) {
+    return {
+      action: 'deny',
+      key: fm.mcp_name ?? null,
+      candidate,
+      reason: 'denied by hand in the note',
+      entry: baseEntry(fm),
+    };
+  }
+  if (status !== APPROVED) {
+    return { action: 'skip', reason: `unrecognised status "${status}"; refusing to guess` };
+  }
+
+  if (fm.type && fm.type !== 'mcp-server') {
+    return {
+      action: 'skip',
+      reason: `type "${fm.type}" is not an MCP server, so it has no place in the gate's registry`,
+    };
+  }
+
+  // The refusal. Deliberately AFTER the approval check, so the log line records
+  // that a human said yes and the rule said no.
+  const grade = fm.grade;
+  const hardFail = fm.hard_fail && fm.hard_fail !== 'null' ? fm.hard_fail : null;
+  if (grade === 'F' || hardFail) {
+    return {
+      action: 'refuse',
+      candidate,
+      reason: hardFail
+        ? `approved by hand, but REFUSED: hard fail (${hardFail})`
+        : 'approved by hand, but REFUSED: grade F',
+      entry: baseEntry(fm),
+    };
+  }
+
+  if (!grade || grade === 'null') {
+    return {
+      action: 'refuse',
+      candidate,
+      reason: 'approved by hand, but REFUSED: there is no grade on this note',
+    };
+  }
+
+  const already = (registry.allow?.servers ?? {})[fm.mcp_name ?? ''];
+  if (already && already.audit_id === fm.audit_id) {
+    return { action: 'skip', reason: 'already allowlisted from this same audit' };
+  }
+
+  return {
+    action: 'allow',
+    key: fm.mcp_name ?? null,
+    candidate,
+    assigned_to: key,
+    reason: `approved by hand, grade ${grade}`,
+    entry: baseEntry(fm),
+  };
+}
+
+function baseEntry(fm) {
+  return {
+    decision: 'allow',
+    url: fm.candidate ?? null,
+    grade: fm.grade === 'null' ? null : (fm.grade ?? null),
+    audit_id: fm.audit_id ?? null,
+    evidence_sha256: fm.evidence_hash === 'null' ? null : (fm.evidence_hash ?? null),
+    /* `assigned_to`, NOT `owner`. The poller already uses `owner` for the
+       scorecard allowlist tenant, and one word meaning two things in one file
+       is how a scoping rule quietly stops meaning anything. */
+    assigned_to: fm.owner === 'null' ? null : (fm.owner ?? null),
+    graded_at: fm.reviewed ?? null,
+    note: 'Approved by hand from a review note. Scoping is recorded, not enforced: ' +
+          'the gate cannot tell which subagent is calling.',
+  };
+}
+
+/** Read a note file's frontmatter into the shape decideForNote wants. */
+export function readNote(path, text) {
+  const fm = parseFrontmatter(text);
+  return { path, frontmatter: fm ?? {}, readable: Boolean(fm) };
+}

package/doorman/src/scorecard.mjs

@@ -0,0 +1,123 @@
+/**
+ * The paid client. The only thing here that can spend money.
+ *
+ * Injected everywhere so tests can pass a stub that THROWS if it is touched.
+ * That is the shape of the guarantee: "no scorecard call happened" is only
+ * checkable if there is one object that would have made it.
+ *
+ * It is also never CONSTRUCTED on a path that must not pay. A skill or a repo
+ * has no tools to drive, so `runVet` does not build one at all rather than
+ * building one and remembering not to call it.
+ *
+ * ## A budget is required, including for the free reads
+ *
+ * `scorecardClient` refuses to exist without one. Making it optional would mean
+ * there is a way to obtain an enqueue-capable client with no spend cap, and a
+ * guarantee with an opt-out is a default. `cached()` and `price()` cost nothing
+ * and still travel with the cap, because the cap is a property of the client,
+ * not a step someone has to remember.
+ */
+
+export class ScorecardError extends Error {}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.api      base url, e.g. https://scorecard.wanessalabs.com
+ * @param {object} opts.budget   from openBudget(). REQUIRED. See above.
+ * @param {Function} [opts.fetch] injectable
+ */
+export function scorecardClient({ api, budget, fetch: f = fetch, timeoutMs = 30_000 } = {}) {
+  if (!api) throw new ScorecardError('scorecardClient needs an api base url');
+  if (!budget || typeof budget.isOpen !== 'function') {
+    throw new ScorecardError(
+      'scorecardClient needs a budget. Build one with openBudget(). This is ' +
+      'not optional: a client with no spend cap is a client that can spend ' +
+      'without limit, and an optional guarantee is a default.',
+    );
+  }
+  const base = api.replace(/\/+$/, '');
+
+  const call = async (path, init) => {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+      const res = await f(base + path, { ...init, signal: ac.signal });
+      return res;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
+  return {
+    api: base,
+
+    /** The cheap read. Returns null when the server has never been graded. */
+    async cached(serverUrl) {
+      const res = await call('/grade?server=' + encodeURIComponent(serverUrl));
+      if (res.status === 404) return null;
+      if (!res.ok) throw new ScorecardError(`cached lookup failed: HTTP ${res.status}`);
+      const j = await res.json();
+      return j.graded ? j : null;
+    },
+
+    /**
+     * What an audit costs, asked rather than assumed.
+     *
+     * A missing price is NOT zero. When the service cannot be reached or gives
+     * an answer this client does not understand, `price_usdc` comes back null
+     * and `openBudget().reserve()` refuses it. That is deliberate: defaulting
+     * an unknown price to zero passes every cap forever.
+     */
+    async price() {
+      const res = await call('/price');
+      if (!res.ok) {
+        return { payment_required: null, price_usdc: null, known: false,
+                 why: `GET /price returned HTTP ${res.status}` };
+      }
+      const j = await res.json().catch(() => null);
+      if (!j || typeof j.price_usdc !== 'number') {
+        return { payment_required: j?.payment_required ?? null, price_usdc: null, known: false,
+                 why: 'the service did not state a decimal price' };
+      }
+      return { ...j, known: true };
+    },
+
+    /**
+     * The paid write. Requires an OPEN permit from the budget this client was
+     * built with, and the permit is checked here rather than trusted, so a
+     * fabricated or already-spent one buys nothing.
+     */
+    async enqueue({ url, name, needed_for, owner = 'doorman', permit }) {
+      if (!budget.isOpen(permit)) {
+        throw new ScorecardError(
+          'enqueue() needs an open budget permit. Call budget.reserve({ ' +
+          'price_usdc, server }) first. A permit is single-use: one that was ' +
+          'already settled or released cannot buy a second audit.',
+        );
+      }
+      const res = await call('/grade', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-owner': owner },
+        body: JSON.stringify([{ url, name, needed_for }]),
+      });
+      if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new ScorecardError(`enqueue failed: HTTP ${res.status} ${body.slice(0, 200)}`);
+      }
+      const j = await res.json();
+      const a = (j.audits ?? [])[0];
+      if (!a?.audit_id) throw new ScorecardError('enqueue returned no audit id');
+      return a;
+    },
+
+    async audit(id) {
+      const res = await call('/grade/' + encodeURIComponent(id));
+      if (!res.ok) throw new ScorecardError(`audit read failed: HTTP ${res.status}`);
+      return res.json();
+    },
+
+    transcriptsUrl(id) {
+      return `${base}/grade/${id}/transcripts`;
+    },
+  };
+}

package/doorman/src/vet.mjs

@@ -0,0 +1,174 @@
+/**
+ * The two-phase vet. Fit first, money second.
+ *
+ * Two questions, in this order, and the order is the whole feature:
+ *
+ *   1. Does MY system need this?      free, local, one model call
+ *   2. Can I afford to find out?      free, local, a spend cap
+ *   3. Is it trustworthy?             paid, external, the scorecard
+ *
+ * Question 2 exists because an agent that can spend on your behalf while you
+ * are asleep is only as safe as the thing that says no. The price is DISCOVERED
+ * from the service, never assumed: a client that defaults an unknown price to
+ * zero passes every cap it has, forever.
+ *
+ * A `redundant` or `out-of-scope` verdict RETURNS BEFORE the scorecard client
+ * is constructed. Not before it is called: before it exists. A path that cannot
+ * spend money is easier to prove than a path that remembers not to.
+ *
+ * Everything is injected, so the whole flow runs offline in tests with a
+ * scorecard stub that throws on contact.
+ */
+
+import { detectCandidate, mayBeGraded } from './candidate.mjs';
+import { fitReview } from './fit-review.mjs';
+import { gatherInventory, renderInventory, findInventoryRoot } from './inventory.mjs';
+import { fetchInstructions } from './instructions.mjs';
+import { sniffInstructions } from './injection.mjs';
+
+/** Verdicts that stop the flow before anything is paid for. */
+export const STOP_VERDICTS = ['redundant', 'out-of-scope'];
+
+/** Owner used when the caller does not supply one. */
+export const DEFAULT_OWNER = 'doorman';
+
+export class VetError extends Error {}
+
+/**
+ * @param {string} input                url, repo, or path
+ * @param {object} deps
+ * @param {object} deps.llm             for the fit review
+ * @param {Function} [deps.makeScorecard]  () => client. NOT called on a stop path.
+ * @param {object} [deps.inventory]     pre-gathered; otherwise read from disk
+ * @param {string} [deps.needed_for]
+ * @param {string} [deps.type]          force the candidate type
+ * @param {Function} [deps.fetch]       for instruction text
+ * @param {Function} [deps.now]
+ */
+export async function runVet(input, deps = {}) {
+  const {
+    llm, makeScorecard, budget, needed_for, type,
+    inventoryRoot, registryDir, fetch: f, now = () => new Date(),
+  } = deps;
+
+  const candidate = detectCandidate(input, type ? { type } : undefined);
+  candidate.needed_for = needed_for;
+
+  const inventory = deps.inventory ?? gatherInventory({
+    root: inventoryRoot ?? findInventoryRoot(process.cwd()),
+    registryDir,
+  });
+
+  const result = {
+    candidate,
+    reviewed: now().toISOString().slice(0, 10),
+    fit: null,
+    scan: null,
+    grade: null,
+    audit_id: null,
+    transcripts: null,
+    cost_usdc: 0,
+    paid: false,
+    price: null,
+    budget: budget
+      ? { per_run_usdc: budget.perRunUsdc, per_day_usdc: budget.perDayUsdc,
+          spent_today_usdc: budget.spentToday(), remaining_usdc: budget.remainingToday() }
+      : null,
+    stopped_at: null,
+  };
+
+  // ── Phase 1: fit. Free. ────────────────────────────────────────────────────
+  result.fit = await fitReview(candidate, inventory, { llm, renderInventory });
+
+  if (STOP_VERDICTS.includes(result.fit.verdict)) {
+    // The point of the whole feature. No client, no request, no charge.
+    result.stopped_at = 'fit';
+    return result;
+  }
+
+  // ── Phase 2a: a skill or a repo is scanned, never graded. ──────────────────
+  if (!mayBeGraded(candidate.type)) {
+    const text = await fetchInstructions(candidate, f ? { fetch: f } : undefined);
+    result.scan = {
+      ...sniffInstructions(text.text, candidate.type === 'repo' ? 'README.md' : 'SKILL.md'),
+      source: text.source,
+      bytes: text.bytes,
+      truncated: text.truncated,
+    };
+    // Said in the result rather than left for the reader to infer from a null.
+    result.grade = null;
+    result.behavioral = 'n/a - no tools to probe';
+    result.stopped_at = 'scan';
+    return result;
+  }
+
+  // ── Phase 2b: an MCP server that the system actually needs. Paid. ──────────
+  if (!makeScorecard) {
+    throw new VetError(
+      'fit passed and this candidate is gradeable, but no scorecard client was ' +
+      'supplied. Refusing to report a verdict with no grade behind it.',
+    );
+  }
+  if (!budget) {
+    throw new VetError(
+      'fit passed and this candidate is gradeable, but no budget was supplied. ' +
+      'Refusing to reach a paid path with no spend cap. Build one with ' +
+      'openBudget() and pass it as deps.budget.',
+    );
+  }
+  const scorecard = makeScorecard();
+
+  // The cache is free, and checking it BEFORE reserving means an exhausted
+  // budget still answers from cache rather than refusing a question that costs
+  // nothing. Refusing a free read to enforce a spend cap would be theatre.
+  const cached = await scorecard.cached(candidate.id);
+  if (cached) {
+    result.grade = cached;
+    result.audit_id = cached.audit_id;
+    result.transcripts = scorecard.transcriptsUrl(cached.audit_id);
+    result.stopped_at = 'cached';
+    return result;                          // a cache hit is still not a purchase
+  }
+
+  // ── Phase 2c: the money. Discover the price, reserve, then spend. ──────────
+  result.price = await scorecard.price();
+  if (!result.price.known) {
+    result.stopped_at = 'price-unknown';
+    result.why = result.price.why;
+    return result;                          // an unknown price is not a free one
+  }
+
+  let permit;
+  try {
+    permit = budget.reserve({
+      price_usdc: result.price.price_usdc,
+      server: candidate.id,
+    });
+  } catch (e) {
+    // A refusal, not a failure. The caller gets a result to print, and the
+    // reason, rather than a stack trace.
+    result.stopped_at = 'budget';
+    result.why = e.message;
+    return result;
+  }
+
+  try {
+    const queued = await scorecard.enqueue({
+      url: candidate.id, name: candidate.host ?? undefined, needed_for, permit,
+    });
+    budget.settle(permit, { audit_id: queued.audit_id });
+    result.audit_id = queued.audit_id;
+    result.transcripts = scorecard.transcriptsUrl(queued.audit_id);
+    result.cost_usdc = permit.price_usdc;
+    result.paid = permit.price_usdc > 0;    // a free call is not a purchase
+    result.stopped_at = 'queued';
+  } catch (e) {
+    // The call did not happen, so the headroom goes back. Releasing on the
+    // error path is the whole reason reserve and settle are separate steps.
+    budget.release(permit, 'enqueue failed: ' + e.message);
+    throw e;
+  }
+  result.budget.spent_today_usdc = budget.spentToday();
+  result.budget.remaining_usdc = budget.remainingToday();
+  return result;
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "clembot-doorman",
+  "version": "0.1.0",
+  "description": "The Package Manager & Security Doorman for Claude Code: inspect your build, recommend vetted MCPs from prompt history, and block rogue tools before context.",
+  "homepage": "https://clembot-doorman.wanessalabs.com",
+  "type": "module",
+  "bin": {
+    "doorman": "doorman/cli/doorman.mjs"
+  },
+  "scripts": {
+    "doctor": "node doorman/cli/doorman.mjs doctor",
+    "test": "node doorman/test/run.mjs && node doorman/test/cli-run.mjs",
+    "test:all": "node doorman/test/run.mjs && node doorman/test/cli-run.mjs && bash doorman/test-gate.sh"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clemenswan/clembot-doorman.git"
+  },
+  "comment": [
+    "Root package so the CLI installs from a clone:",
+    "  git clone https://github.com/clemenswan/clembot-doorman && npm i -g ./clembot-doorman",
+    "",
+    "It deliberately declares NO dependencies. This is a giveaway: every",
+    "dependency is one more thing that can fail to install on somebody else's",
+    "machine, and a gate that fails to start is a gate that fails open.",
+    "",
+    "The bin points into doorman/cli/ rather than duplicating it, and",
+    "report.mjs resolves the scorecard runner at runtime rather than assuming",
+    "the author's directory layout."
+  ],
+  "files": [
+    "doorman/cli",
+    "doorman/src",
+    "doorman/registry",
+    "doorman/hooks",
+    "doorman/agents",
+    "doorman/commands",
+    "doorman/skills",
+    "doorman/scripts",
+    "doorman/recipes",
+    "doorman/.claude",
+    "doorman/.claude-plugin",
+    "doorman/.mcp.json",
+    "doorman/install.sh",
+    "doorman/README.md",
+    "doorman/package.json",
+    ".claude-plugin",
+    "WALKTHROUGH.md"
+  ]
+}