@secondlayer/sentinel 0.1.1 → 0.2.0

package/dist/cli.js

@@ -85,10 +85,14 @@ class SentinelError extends Error {
     this.name = "SentinelError";
   }
 }
-var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : `asset:${s.asset}`;
+var rowsOf = (intents) => intents.flatMap((i) => i.rows);
+var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : s.kind === "group" ? `group:${s.group}` : `asset:${s.asset}`;
+var CONTROL_NAME = "Control changes";
 function subjectName(s, units) {
   if (s.kind === "fn")
     return s.fn;
+  if (s.kind === "group")
+    return CONTROL_NAME;
   if (units?.symbol)
     return units.symbol;
   if (s.asset.toLowerCase() === "stx")
@@ -120,7 +124,7 @@ function resolveSubject(watches, name) {
   const hits = groups.filter((g) => {
     const s = g.watches[0].subject;
     const asset = s.kind === "asset" ? s.asset.toLowerCase() : null;
-    return g.name.toLowerCase() === q || g.key.toLowerCase() === q || asset === q || asset !== null && asset.split("::")[1] === q;
+    return g.name.toLowerCase() === q || g.key.toLowerCase() === q || s.kind === "group" && q === s.group || asset === q || asset !== null && asset.split("::")[1] === q;
   });
   if (hits.length === 1)
     return hits[0];
@@ -172,26 +176,16 @@ function ruleSummary(rule, units) {
     }
   }
 }
-function kindTag(rule) {
-  switch (rule.kind) {
-    case "signature":
-      return "finding";
-    case "outflowSingle":
-    case "outflowWindow":
-    case "valueNewActor":
-      return "outflow";
-    case "callerAllowlist":
-    case "actor":
-      return "who-acts";
-    case "audit":
-      return rule.triggerClass === "governance.proposal_submitted" ? "governance" : "upgrade";
+function intentLine(i) {
+  const t = i.threshold;
+  if (i.kind !== "money_out" || !t)
+    return i.summary;
+  const units = i.units ?? null;
+  if (t.amount === null) {
+    const sug = t.suggested ? ` (suggested ${amountText(t.suggested.amount, units)}, ${t.suggested.basis})` : "";
+    return `no threshold yet: every outflow alerts${sug}`;
   }
-}
-function subjectStatus(ws) {
-  const st = ws.map((w) => w.status);
-  if (st.includes("live"))
-    return "live";
-  return st.length > 0 && st.every((x) => x === "paused") ? "paused" : "suggested";
+  return `${amountText(t.amount, units)} or more in one tx · ${t.basis}`;
 }
 var isMutableRule = (rule) => rule.kind !== "signature" && rule.kind !== "audit";
 function mutedUntilOf(w, now = Date.now()) {
@@ -256,11 +250,13 @@ var HOUR_MS = 3600000;
 var muteEnd = (hours) => new Date(Date.now() + Math.min(hours * HOUR_MS, 7 * 24 * HOUR_MS - 60000)).toISOString();
 async function watchContext(client, planId) {
   const plan = await client.plan(planId);
+  const { intents } = await client.watches(planId);
   return {
     planId,
     contractId: plan.contractId,
     access: plan.access,
-    watches: (await client.watches(planId)).watches
+    intents,
+    watches: rowsOf(intents)
   };
 }
 async function savedMonitor(client, planId) {
@@ -423,6 +419,26 @@ async function whoami(client, io) {
   return 0;
 }
 
+// client/kind.ts
+var isGreen = (f) => f.poc === "green";
+function findingKind(f) {
+  if (f.disposition === "refuted" || f.verdict === "refuted")
+    return "refuted";
+  if (f.class === "centralization" || f.disposition === "waived")
+    return "trust";
+  if (f.class === "bug" && f.verdict === "confirmed" && f.reverified === true && isGreen(f)) {
+    return "exploitable";
+  }
+  return "worth_a_look";
+}
+var URGENT_CONSEQUENCES = new Set(["authority", "code", "value"]);
+var KIND_LABEL = {
+  exploitable: "Exploitable",
+  trust: "Trust assumption",
+  worth_a_look: "Worth a look",
+  refuted: "refuted"
+};
+
 // client/labels.ts
 var isPrelaunchKey = (id) => id.startsWith("github:") || id.startsWith("gist:");
 function contractName(id) {
@@ -439,6 +455,294 @@ var MONITOR_LABELS = {
 };
 var monitoringLabel = (status) => status ? MONITOR_LABELS[status] ?? status : "not on yet";
 
+// client/handoff.ts
+var DEFAULT_FILE = "sentinel-poc.ts";
+var pocFileName = (f) => f.proof?.file ?? DEFAULT_FILE;
+function runCommand(opts) {
+  const lines = [`# save the PoC above as ${opts.file}, then in your own checkout:`];
+  if (opts.commit)
+    lines.push(`git checkout ${opts.commit}   # the commit Sentinel reviewed`);
+  const where = opts.substrate === "fork" ? "needs a Stacks RPC" : "airgapped, no network";
+  lines.push(`bun run ${opts.file}   # @stacks/clarinet-sdk — ${where}`);
+  return lines.join(`
+`);
+}
+function handoffBundle(f, ctx) {
+  const proof = f.proof;
+  const file = pocFileName(f);
+  const poc = proof?.script ? {
+    file,
+    substrate: proof.substrate ?? null,
+    reproduced: !!proof.reproduced,
+    exitCode: proof.exitCode ?? null,
+    source: proof.script
+  } : null;
+  return {
+    contract: ctx.contract,
+    fn: f.targetFn ?? null,
+    commit: ctx.commit ?? null,
+    poc,
+    runCommand: poc ? runCommand({ commit: ctx.commit, file, substrate: poc.substrate }) : null
+  };
+}
+function assertionsOf(output) {
+  const ratio = output.match(/(\d+)\s*\/\s*(\d+)\s*assertions?/i);
+  if (ratio)
+    return `${ratio[1]}/${ratio[2]}`;
+  const passed = output.match(/(\d+)\s*assertions?\s*passed/i);
+  return passed ? `${passed[1]} passed` : null;
+}
+var FENCE = "```";
+var FOOTER = "Sentinel's findings are a starting point for your own review, not an audit sign-off.";
+var KIND_LINE = {
+  exploitable: "Exploitable (verified, re-verified, reproduced in the sandbox)",
+  trust: "Trust assumption (watched: Sentinel alerts when it's used)",
+  worth_a_look: "Worth a look (not proven exploitable)",
+  refuted: "Refuted"
+};
+var tick = (s) => `\`${s}\``;
+var cell = (s) => s.replace(/\|/g, "\\|").replace(/\n/g, " ");
+var num = (n) => n.toLocaleString("en-US");
+function printed(output) {
+  const lines = output.replace(/\[SENTINEL-POC-TRACE\][\s\S]*?\[\/SENTINEL-POC-TRACE\]/g, "").split(`
+`).filter((l) => l.trim());
+  return lines.slice(-40).join(`
+`);
+}
+function movedMd(trace) {
+  const keys = Object.keys(trace.series ?? {}).filter((k) => trace.steps.some((s) => s.values?.[k] !== undefined));
+  const name = (k) => trace.series?.[k] ?? k;
+  const unit = trace.unit ? ` ${trace.unit}` : "";
+  const changes = (i) => {
+    const prev = trace.steps[i - 1]?.values;
+    const now = trace.steps[i].values;
+    if (!prev || !now)
+      return [];
+    return keys.filter((k) => now[k] !== undefined && prev[k] !== undefined && now[k] !== prev[k]).map((k) => `${name(k)} ${num(prev[k])} → ${num(now[k])}${unit}`);
+  };
+  const first = trace.steps.findIndex((_, i) => changes(i).length > 0);
+  const rows = trace.steps.map((s, i) => {
+    const call = [s.call && tick(s.call), s.result && `→ ${tick(s.result)}`].filter(Boolean).join(" ");
+    const start = keys.filter((k) => s.values?.[k] !== undefined).map((k) => `${name(k)} ${num(s.values?.[k])}${unit}`).join(" · ");
+    const change = i === 0 ? start || "start" : changes(i).join(" · ") || "no change";
+    return `| ${i + 1} ${cell(s.label)} | ${cell(call || "—")} | ${cell(change)} |`;
+  });
+  return [
+    "## What the PoC moved",
+    first > 0 ? `**${changes(first).join("; ")} at step ${first + 1} (${trace.steps[first].label}).**` : "No tracked value changed across the steps.",
+    "",
+    "| Step | Call | Value change |",
+    "|---|---|---|",
+    ...rows,
+    ""
+  ];
+}
+function variantOf(f) {
+  if (f.proof?.reproduced)
+    return "reproduced";
+  if (f.proof && !f.proof.unavailable && !f.proof.errored && f.proof.script)
+    return "notrepro";
+  if (f.verdict !== "confirmed")
+    return "lead";
+  return "analysis";
+}
+function where(f, ctx) {
+  const at = ctx.commit ? ` at commit ${tick(ctx.commit.slice(0, 7))}` : "";
+  return f.targetFn ? `Open ${tick(f.targetFn)} in ${tick(contractName(ctx.contract))}${at} and show the function with ~10 lines of context. Point at the lines this finding is about and explain in your own words what they do.` : `Find the code this finding describes in ${tick(contractName(ctx.contract))}${at} and show it with ~10 lines of context. Explain in your own words what it does.`;
+}
+function contextMd(f, ctx, kind) {
+  return [
+    "## Context",
+    `- Contract: ${tick(ctx.contract)}`,
+    ...ctx.commit ? [`- Commit reviewed: ${tick(ctx.commit.slice(0, 7))}`] : [],
+    ...f.targetFn ? [`- Function: ${tick(f.targetFn)}`] : [],
+    `- Kind: ${KIND_LINE[kind]}`
+  ];
+}
+function reportBackMd(ctx, extra) {
+  return [
+    "## How to report back",
+    `- Cite every claim with ${tick("file:line")}${ctx.commit ? ` at commit ${tick(ctx.commit.slice(0, 7))}` : ""}.`,
+    "- Show the code you discuss, quoted from the repo, not paraphrased.",
+    extra,
+    "- Keep two sections: **Facts** (what the code and the run show) and **Assessment** (your conclusions, each with a confidence level). Don't mix them.",
+    "- Don't change contract code until the team has chosen an approach.",
+    ""
+  ];
+}
+function tailMd(ctx, withPoc) {
+  return [
+    "",
+    "## Pull it again",
+    `${FENCE}shell`,
+    `npx @secondlayer/sentinel finding ${ctx.planId} ${ctx.index}${withPoc ? " --poc --run" : ""}`,
+    FENCE,
+    `MCP: ${tick(`get_finding { planId: "${ctx.planId}", index: ${ctx.index} }`)} returns this finding as JSON${withPoc ? ", the PoC source and the run command" : ""}.`,
+    "",
+    "---",
+    FOOTER
+  ];
+}
+function issueMd(f, withCondition) {
+  return [
+    "## The issue",
+    f.headline && f.headline !== f.title ? `${f.headline} (${f.title})` : f.title,
+    ...f.blastRadius ? ["", `**Impact:** ${f.blastRadius}`] : [],
+    ...withCondition && f.precondition ? ["", `**Exploitable when:** ${f.precondition}`] : [],
+    ""
+  ];
+}
+function prelaunchBrief(f, ctx, kind) {
+  const kindLine = kind === "exploitable" ? "Exploitable · look before launch" : kind === "trust" ? "Trust assumption" : "Worth a look before launch";
+  return [
+    "# Task: review a Sentinel finding on pre-launch code",
+    "",
+    `Sentinel found an issue${f.targetFn ? ` in ${tick(f.targetFn)}` : ""}: ${f.title}. PoCs and exploit detail open once Sentinel confirms this code isn't already live on mainnet; possible approaches are shown now, so this brief carries the finding and a direction, not the PoC. Look at the code before launch: the watch arms at launch, but it isn't a substitute for the review.`,
+    "",
+    "## Start here",
+    `1. ${where(f, ctx)}`,
+    "2. Only then discuss approaches that fit this codebase's design.",
+    "",
+    "## How to report back",
+    `- Cite every claim with ${tick("file:line")}${ctx.commit ? ` at commit ${tick(ctx.commit.slice(0, 7))}` : ""}.`,
+    "- Keep **Facts** and **Assessment** apart, with a confidence level on each conclusion.",
+    "",
+    "## Context",
+    `- Contract: ${tick(contractName(ctx.contract))} (pre-launch)${ctx.commit ? `, commit ${tick(ctx.commit.slice(0, 7))}` : ""}`,
+    `- ${f.targetFn ? `Function: ${tick(f.targetFn)} · ` : ""}Kind: ${kindLine}`,
+    "",
+    ...issueMd(f, false),
+    ...f.recommendedAction ? ["## One direction to consider (not a verified patch)", f.recommendedAction, ""] : [],
+    "---",
+    FOOTER
+  ].join(`
+`);
+}
+function trustBrief(f, ctx) {
+  return [
+    "# Task: review a trust assumption and decide whether to reduce it",
+    "",
+    `Sentinel found a power held by design${f.targetFn ? ` in ${tick(f.targetFn)}` : ""}: ${f.title}. It's a trust assumption, not a bug, so there is nothing to reproduce. Review it and decide whether the trust it asks of your users fits your design.`,
+    "",
+    "## Start here",
+    `1. ${where(f, ctx)}`,
+    `2. Find every place that reads what ${f.targetFn ? tick(f.targetFn) : "this power"} changes, and show each one, so the reach of this power is clear.`,
+    "3. Only then discuss options that fit this codebase's design.",
+    "",
+    ...reportBackMd(ctx, "- There is no PoC for a trust assumption. Don't write an exploit for it."),
+    ...contextMd(f, ctx, "trust"),
+    "- Class: trust assumption (a power held by design)",
+    "- Evidence: checked by Sentinel's adversarial verifier. No PoC; nothing to run.",
+    "",
+    "## What it is",
+    f.headline && f.headline !== f.title ? `${f.headline} (${f.title})` : f.title,
+    ...f.powers?.length ? [
+      "",
+      "**Powers:**",
+      ...f.powers.map((p) => `- ${p.holder} can ${p.can}${p.fn ? ` (${tick(p.fn)})` : ""}`)
+    ] : [],
+    ...f.blastRadius ? ["", `**Impact:** ${f.blastRadius}`] : [],
+    ...f.precondition ? ["", `**Usable when:** ${f.precondition}`] : [],
+    "",
+    ...f.recommendedAction ? ["## Options to consider (not a patch)", `- ${f.recommendedAction}`, ""] : [],
+    "## If you change it",
+    "- A test for the new behavior.",
+    "- A test that an account without the role is still refused.",
+    ...tailMd(ctx, false)
+  ].join(`
+`);
+}
+function refutedBrief(f, ctx) {
+  return [
+    "# Note: a Sentinel finding refuted on re-check",
+    "",
+    `Sentinel's verifier re-examined this${f.targetFn ? ` (${tick(f.targetFn)})` : ""} and showed it can't happen: ${f.title}. It's kept for the record and isn't watched.`,
+    "",
+    ...contextMd(f, ctx, "refuted"),
+    ...tailMd(ctx, false)
+  ].join(`
+`);
+}
+function bugBrief(f, ctx, kind) {
+  const v = variantOf(f);
+  const bundle = handoffBundle(f, { contract: ctx.contract, commit: ctx.commit });
+  const poc = bundle.poc;
+  const p = f.proof;
+  const asserted = p?.output ? assertionsOf(p.output) : null;
+  const counted = asserted?.includes("/") ? `${asserted} assertions, ` : asserted ? `${asserted.replace(" passed", "")} assertions passed, ` : "";
+  const ran = `${counted}exit ${p?.exitCode ?? "?"}`;
+  const sandbox = p?.substrate === "fork" ? "a mainnet-fork sandbox" : `an airgapped sandbox (${tick("--network none")})`;
+  const what = `Sentinel found an issue${f.targetFn ? ` in ${tick(f.targetFn)}` : ""}: ${f.title}`;
+  const open = {
+    reproduced: `${what}. It reproduced with the PoC below. Review the affected code, choose an approach that fits your design, then confirm the PoC no longer succeeds.`,
+    notrepro: `${what}. Its verifier confirmed it by analysis, but the PoC below ran and did not reproduce it. Review the affected code and the run, and decide whether it applies to your deployment.`,
+    analysis: `${what}. Its verifier confirmed it by analysis; no PoC result yet. ${poc ? "Run the PoC below in your own tooling, then review" : "Review"} the affected code and choose an approach that fits your design.`,
+    lead: `An auditor flagged an issue${f.targetFn ? ` in ${tick(f.targetFn)}` : ""}: ${f.title}. The verifier hasn't confirmed it, so treat it as a lead.`
+  }[v];
+  const evidence = {
+    reproduced: `confirmed by Sentinel's adversarial verifier${f.reverified ? ", re-verified by a second independent pass" : ""}, then reproduced in ${sandbox}: ${ran}.${f.reverified ? "" : " Not re-verified yet."}`,
+    notrepro: `confirmed by Sentinel's adversarial verifier. The PoC ran in ${sandbox} and did not reproduce it (${ran}). Verified by analysis only.`,
+    analysis: "confirmed by Sentinel's adversarial verifier. No PoC result yet.",
+    lead: "found by an auditor, not yet confirmed by the verifier. Treat it as a lead."
+  }[v];
+  const runStep = poc ? v === "notrepro" ? `2. Save the PoC below as ${tick(poc.file)} and run it. Show the output, compare it with Sentinel's run below, and say whether it reproduces in this codebase.` : v === "reproduced" ? `2. Save the PoC below as ${tick(poc.file)} and run it. Show the output and say whether it reproduces.` : `2. Save the PoC below as ${tick(poc.file)} and run it. Show the output and say whether it reproduces. If its setup doesn't match this codebase, adapt it and list what you changed.` : null;
+  const out = p?.output ? printed(p.output) : "";
+  return [
+    "# Task: investigate a Sentinel finding and decide on an approach",
+    "",
+    `${open}${poc ? " Simnet only; nothing touches mainnet." : ""}`,
+    "",
+    "## Start here",
+    `1. ${where(f, ctx)}`,
+    ...runStep ? [runStep] : [],
+    `${runStep ? 3 : 2}. Only then discuss approaches that fit this codebase's design.`,
+    "",
+    ...reportBackMd(ctx, poc ? "- Show the exact command you ran and its full output." : "- Say what you checked and how."),
+    ...contextMd(f, ctx, kind),
+    f.class === "bug" ? "- Class: bug (not a trust assumption; no privileged role needed)" : `- Class: ${f.class}`,
+    `- Evidence: ${evidence}`,
+    "",
+    ...v === "reproduced" && p?.trace ? movedMd(p.trace) : [],
+    ...issueMd(f, true),
+    ...poc ? [
+      v === "notrepro" ? `## PoC as it ran (save as ${tick(poc.file)})` : `## PoC (save as ${tick(poc.file)})`,
+      `${FENCE}typescript`,
+      poc.source,
+      FENCE,
+      "",
+      "## Run it",
+      `${FENCE}shell`,
+      bundle.runCommand ?? "",
+      FENCE,
+      ...out && (v === "reproduced" || v === "notrepro") ? [
+        v === "reproduced" ? "Sentinel's output, before any change:" : "Sentinel's run printed:",
+        FENCE,
+        out,
+        FENCE
+      ] : [],
+      ""
+    ] : [],
+    ...f.recommendedAction ? ["## One direction to consider (not a verified patch)", f.recommendedAction, ""] : [],
+    ...poc ? [
+      "## Confirm a change",
+      "- Re-run the PoC. With your change in place it should no longer succeed.",
+      "- Consider keeping the PoC as a regression test, with its assertions flipped to expect the failure."
+    ] : [],
+    ...tailMd(ctx, !!poc)
+  ].join(`
+`);
+}
+function agentBrief(f, ctx) {
+  const kind = f.kind ?? findingKind(f);
+  if (ctx.prelaunch && kind !== "refuted")
+    return prelaunchBrief(f, ctx, kind);
+  if (kind === "refuted")
+    return refutedBrief(f, ctx);
+  if (kind === "trust")
+    return trustBrief(f, ctx);
+  return bugBrief(f, ctx, kind);
+}
+
 // cli/sentinel.ts
 var USAGE = `sentinel <command>
 
@@ -452,7 +756,8 @@ var USAGE = `sentinel <command>
 
   plans                       your contracts: monitoring, worst evidence, plan id
   plan <id> [--json]          verdict and findings (--json: the raw v1 response)
-  finding <id> <n> [--json]   one finding
+  finding <id> <n> [--poc] [--run] [--brief] [--json]   one finding; --poc adds the PoC source, --run the command
+                              to re-run it, --brief the agent brief (the finding page's "Copy agent brief")
   runs <id>                   follow-up runs on a plan
   watch <id>                  follow running runs until none are left
   reverify <id> [--yes]       check a plan's leads again (stronger second pass, $3); only starts with --yes
@@ -486,9 +791,9 @@ credential: SENTINEL_API_KEY, then --token <key>, then sentinel login. env: SENT
 `;
 var POLL_MS = 5000;
 var VALUE_FLAGS = new Set(["--email", "--webhook", "--slack", "--contract"]);
-var cell = (v, empty = "—") => v === null || v === undefined || v === "" ? empty : String(v);
+var cell2 = (v, empty = "—") => v === null || v === undefined || v === "" ? empty : String(v);
 var table = (rows) => {
-  const text = rows.map((r) => r.map((c) => cell(c)));
+  const text = rows.map((r) => r.map((c) => cell2(c)));
   const w = text[0]?.map((_, i) => Math.max(...text.map((r) => r[i].length))) ?? [];
   return text.map((r) => r.map((c, i) => c.padEnd(w[i])).join("  ").trimEnd());
 };
@@ -499,7 +804,7 @@ var phaseOf = (r) => {
 var verdictLine = (p) => {
   const r = p.report;
   const head = `${p.contractId}  ${p.status}`;
-  return r ? `${head}  ${cell(r.severity)}/${cell(r.class)}  alert=${cell(r.alertLevel)}` : head;
+  return r ? `${head}  ${cell2(r.severity)}/${cell2(r.class)}  alert=${cell2(r.alertLevel)}` : head;
 };
 async function run(argv, io) {
   const flags = [];
@@ -524,7 +829,17 @@ ${USAGE}` : USAGE);
   }
   const [cmd, id, n] = args;
   const json = flags.includes("--json");
-  const known = new Set(["--json", "--yes", "--help", "--force", "--with-token", "--from-repo"]);
+  const known = new Set([
+    "--json",
+    "--yes",
+    "--help",
+    "--force",
+    "--with-token",
+    "--from-repo",
+    "--poc",
+    "--run",
+    "--brief"
+  ]);
   if (flags.some((f) => !known.has(f)))
     return usage(`Unknown flag ${flags.find((f) => !known.has(f))}`);
   if (flags.includes("--help") || !cmd || cmd === "help") {
@@ -564,8 +879,7 @@ ${USAGE}` : USAGE);
           io.out("Exploit detail is hidden until you verify control in the web app.");
         const rows = (p.report?.findings ?? []).map((f, i) => [
           i,
-          f.severity,
-          f.class,
+          f.kind ? KIND_LABEL[f.kind] : f.class,
           f.verdict,
           f.disposition,
           f.title
@@ -581,14 +895,50 @@ ${USAGE}` : USAGE);
         if (n === undefined || !/^\d+$/.test(n))
           return usage("sentinel finding needs a plan id and a finding number");
         const f = await io.client.finding(id, Number(n));
+        const wantPoc = flags.includes("--poc");
+        const wantRun = flags.includes("--run");
+        const wantBrief = flags.includes("--brief");
+        const p = wantPoc || wantRun || wantBrief ? await io.client.plan(id) : null;
+        const commit = p?.report?.target?.commit ?? null;
+        const bundle = p && (wantPoc || wantRun) ? handoffBundle(f, { contract: p.contractId, commit }) : null;
+        if (p && wantBrief) {
+          io.out(agentBrief(f, {
+            contract: p.contractId,
+            commit,
+            planId: id,
+            index: Number(n),
+            prelaunch: p.access === "prelaunch"
+          }));
+          return 0;
+        }
         if (json) {
-          io.out(JSON.stringify(f, null, 2));
+          io.out(JSON.stringify(bundle ? { finding: f, poc: bundle.poc, runCommand: bundle.runCommand } : f, null, 2));
           return 0;
         }
+        const kind = f.kind ? KIND_LABEL[f.kind] : f.class;
+        const alerts = f.alertLevel ? `alerts: ${f.alertLevel}` : null;
         io.out(`${f.title}
-${[f.severity, f.class, f.verdict, f.disposition].map((v) => cell(v)).join(" ")}`);
+${[kind, f.verdict, f.disposition, alerts].filter(Boolean).map((v) => cell2(v)).join(" · ")}`);
         if (f.headline)
           io.out(f.headline);
+        if (wantPoc) {
+          if (bundle?.poc) {
+            io.out(`
+# PoC · ${bundle.poc.file}`);
+            io.out(bundle.poc.source);
+          } else
+            io.out(`
+No PoC is stored for this finding.`);
+        }
+        if (wantRun) {
+          if (bundle?.runCommand) {
+            io.out(`
+# Run it yourself`);
+            io.out(bundle.runCommand);
+          } else
+            io.out(`
+No run command: no PoC is stored for this finding.`);
+        }
         return 0;
       }
       case "runs": {
@@ -808,7 +1158,7 @@ async function monitoring(cmd, pos, on, flags, values, io, usage) {
       return 0;
     }
     const r = await io.client.watchContract(first);
-    io.out("watches" in r ? `Monitoring ${r.contractId}. Manage it with plan ${r.planId}.` : `Sentinel is still making the plan (${r.planId}). Run this again in a few minutes.`);
+    io.out("intents" in r ? `Monitoring ${r.contractId}. Manage it with plan ${r.planId}.` : `Sentinel is still making the plan (${r.planId}). Run this again in a few minutes.`);
     return 0;
   }
   if (!first)
@@ -825,21 +1175,16 @@ async function monitoring(cmd, pos, on, flags, values, io, usage) {
   const ctx = await watchContext(io.client, planId);
   if (cmd === "watches") {
     if (flags.includes("--json")) {
-      io.out(JSON.stringify({ watches: ctx.watches }, null, 2));
+      io.out(JSON.stringify({ intents: ctx.intents }, null, 2));
       return 0;
     }
     if (ctx.access === "claimed") {
       io.out("Exploit detail is hidden until you verify control in the web app.");
     }
-    for (const g of groupSubjects(ctx.watches)) {
-      const muted = g.watches.map((w) => mutedUntilOf(w)).find(Boolean);
-      io.out([
-        g.name,
-        [...new Set(g.watches.map((w) => kindTag(w.rule)))].join("+"),
-        subjectStatus(g.watches),
-        muted ? `muted until ${muted}` : ""
-      ].filter(Boolean).join("  "));
-      for (const w of g.watches)
+    for (const i of ctx.intents) {
+      const muted = i.rows.map((w) => mutedUntilOf(w)).find(Boolean);
+      io.out([i.title, i.tag, i.on ? "on" : "off", intentLine(i), muted ? `muted until ${muted}` : ""].filter(Boolean).join("  "));
+      for (const w of i.rows)
         io.out(`  ${w.status.padEnd(14)}${ruleSummary(w.rule, w.units)}`);
     }
     return 0;

package/dist/index.js

@@ -79,10 +79,14 @@ class SentinelError extends Error {
     this.name = "SentinelError";
   }
 }
-var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : `asset:${s.asset}`;
+var rowsOf = (intents) => intents.flatMap((i) => i.rows);
+var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : s.kind === "group" ? `group:${s.group}` : `asset:${s.asset}`;
+var CONTROL_NAME = "Control changes";
 function subjectName(s, units) {
   if (s.kind === "fn")
     return s.fn;
+  if (s.kind === "group")
+    return CONTROL_NAME;
   if (units?.symbol)
     return units.symbol;
   if (s.asset.toLowerCase() === "stx")
@@ -114,7 +118,7 @@ function resolveSubject(watches, name) {
   const hits = groups.filter((g) => {
     const s = g.watches[0].subject;
     const asset = s.kind === "asset" ? s.asset.toLowerCase() : null;
-    return g.name.toLowerCase() === q || g.key.toLowerCase() === q || asset === q || asset !== null && asset.split("::")[1] === q;
+    return g.name.toLowerCase() === q || g.key.toLowerCase() === q || s.kind === "group" && q === s.group || asset === q || asset !== null && asset.split("::")[1] === q;
   });
   if (hits.length === 1)
     return hits[0];
@@ -181,6 +185,17 @@ function kindTag(rule) {
       return rule.triggerClass === "governance.proposal_submitted" ? "governance" : "upgrade";
   }
 }
+function intentLine(i) {
+  const t = i.threshold;
+  if (i.kind !== "money_out" || !t)
+    return i.summary;
+  const units = i.units ?? null;
+  if (t.amount === null) {
+    const sug = t.suggested ? ` (suggested ${amountText(t.suggested.amount, units)}, ${t.suggested.basis})` : "";
+    return `no threshold yet: every outflow alerts${sug}`;
+  }
+  return `${amountText(t.amount, units)} or more in one tx · ${t.basis}`;
+}
 function subjectStatus(ws) {
   const st = ws.map((w) => w.status);
   if (st.includes("live"))
@@ -250,11 +265,13 @@ var HOUR_MS = 3600000;
 var muteEnd = (hours) => new Date(Date.now() + Math.min(hours * HOUR_MS, 7 * 24 * HOUR_MS - 60000)).toISOString();
 async function watchContext(client, planId) {
   const plan = await client.plan(planId);
+  const { intents } = await client.watches(planId);
   return {
     planId,
     contractId: plan.contractId,
     access: plan.access,
-    watches: (await client.watches(planId)).watches
+    intents,
+    watches: rowsOf(intents)
   };
 }
 async function savedMonitor(client, planId) {
@@ -272,6 +289,7 @@ async function planOfContract(client, contractId) {
   return hit.planId;
 }
 export {
+  CONTROL_NAME,
   CREDITS_API_URL,
   DEFAULT_BASE_URL,
   NOT_LOGGED_IN,
@@ -282,6 +300,7 @@ export {
   createClient,
   creditsUrl,
   groupSubjects,
+  intentLine,
   isMutableRule,
   kindTag,
   muteEnd,
@@ -291,6 +310,7 @@ export {
   readTokenFile,
   resolveSubject,
   resolveToken,
+  rowsOf,
   ruleSummary,
   savedChoices,
   savedMonitor,

package/dist/kind.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What a finding is, for the people watching the contract (docs/product/system.md § "How findings are
+ * shown"). The user sees a kind, never an audit severity; severity lives on as the alert level of the
+ * finding's watch. Dependency-free and the ONE derivation: the API stamps `kind` and `alertLevel` on every
+ * finding it returns, so the page, the CLI and the MCP tools never derive it differently.
+ */
+/**
+ *   exploitable   a bug, verified, independently RE-verified, and reproduced green in the sandbox. Rare.
+ *   trust         a power held by design (centralization / trust assumption, accepted or not)
+ *   worth_a_look  everything else not refuted: analysis only, not reproduced yet, a lead, or reproduced
+ *                 but not re-verified yet
+ *   refuted       refuted on re-check
+ */
+export type FindingKind = "exploitable" | "trust" | "worth_a_look" | "refuted";
+/** How a finding's watch pages: urgent, or normal. */
+export type AlertLevel = "urgent" | "normal";
+/** A watched function's dominant consequence (engine/watch-select/facts.ts `Consequence`, copied: no deps). */
+export type Consequence = "authority" | "code" | "value" | "param" | "none";
+/** The finding fields the kind reads. The app's ReportFinding and the client's Finding both satisfy it. */
+export type KindInput = {
+    class: string;
+    verdict: string;
+    disposition: string;
+    /** The PoC status after the credibility gates (a later reproduction's, once one lands). */
+    poc?: string;
+    /** A second, independent verifier pass confirmed it. Absent: not re-verified (yet). */
+    reverified?: boolean;
+};
+/** Reproduced green in the sandbox AND past the credibility gates. A PoC that printed "reproduced" but
+ *  that Gate 3 downgraded (an incomplete freeze proof) is `pending`, so it is not green here. */
+export declare const isGreen: (f: Pick<KindInput, "poc">) => boolean;
+export declare function findingKind(f: KindInput): FindingKind;
+/**
+ * The alert level of a finding's watch. A trust assumption pages urgently only when its function changes
+ * who controls the contract, swaps code it calls, or moves value; an unknown consequence is `normal`
+ * (the caller logs it). A refuted finding has no watch.
+ */
+export declare function alertLevelFor(kind: Exclude<FindingKind, "refuted">, consequence?: Consequence | null): AlertLevel;
+/** A kind as every surface names it (the page's chip, the plan list, the CLI, the agent brief). */
+export declare const KIND_LABEL: Record<FindingKind, string>;
+/** Plan-list order: Exploitable first, then trust assumptions, then worth a look; refuted last. */
+export declare const KIND_ORDER: FindingKind[];

package/dist/mcp.js

@@ -12659,10 +12659,14 @@ class SentinelError extends Error {
     this.name = "SentinelError";
   }
 }
-var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : `asset:${s.asset}`;
+var rowsOf = (intents) => intents.flatMap((i) => i.rows);
+var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : s.kind === "group" ? `group:${s.group}` : `asset:${s.asset}`;
+var CONTROL_NAME = "Control changes";
 function subjectName(s, units) {
   if (s.kind === "fn")
     return s.fn;
+  if (s.kind === "group")
+    return CONTROL_NAME;
   if (units?.symbol)
     return units.symbol;
   if (s.asset.toLowerCase() === "stx")
@@ -12694,7 +12698,7 @@ function resolveSubject(watches, name) {
   const hits = groups.filter((g) => {
     const s = g.watches[0].subject;
     const asset = s.kind === "asset" ? s.asset.toLowerCase() : null;
-    return g.name.toLowerCase() === q || g.key.toLowerCase() === q || asset === q || asset !== null && asset.split("::")[1] === q;
+    return g.name.toLowerCase() === q || g.key.toLowerCase() === q || s.kind === "group" && q === s.group || asset === q || asset !== null && asset.split("::")[1] === q;
   });
   if (hits.length === 1)
     return hits[0];
@@ -12746,20 +12750,16 @@ function ruleSummary(rule, units) {
     }
   }
 }
-function kindTag(rule) {
-  switch (rule.kind) {
-    case "signature":
-      return "finding";
-    case "outflowSingle":
-    case "outflowWindow":
-    case "valueNewActor":
-      return "outflow";
-    case "callerAllowlist":
-    case "actor":
-      return "who-acts";
-    case "audit":
-      return rule.triggerClass === "governance.proposal_submitted" ? "governance" : "upgrade";
+function intentLine(i) {
+  const t = i.threshold;
+  if (i.kind !== "money_out" || !t)
+    return i.summary;
+  const units = i.units ?? null;
+  if (t.amount === null) {
+    const sug = t.suggested ? ` (suggested ${amountText(t.suggested.amount, units)}, ${t.suggested.basis})` : "";
+    return `no threshold yet: every outflow alerts${sug}`;
   }
+  return `${amountText(t.amount, units)} or more in one tx · ${t.basis}`;
 }
 function subjectStatus(ws) {
   const st = ws.map((w) => w.status);
@@ -12830,11 +12830,13 @@ var HOUR_MS = 3600000;
 var muteEnd = (hours) => new Date(Date.now() + Math.min(hours * HOUR_MS, 7 * 24 * HOUR_MS - 60000)).toISOString();
 async function watchContext(client, planId) {
   const plan = await client.plan(planId);
+  const { intents } = await client.watches(planId);
   return {
     planId,
     contractId: plan.contractId,
     access: plan.access,
-    watches: (await client.watches(planId)).watches
+    intents,
+    watches: rowsOf(intents)
   };
 }
 async function savedMonitor(client, planId) {
@@ -20279,6 +20281,316 @@ var EMPTY_COMPLETION_RESULT = {
   }
 };
 
+// client/kind.ts
+var isGreen = (f) => f.poc === "green";
+function findingKind(f) {
+  if (f.disposition === "refuted" || f.verdict === "refuted")
+    return "refuted";
+  if (f.class === "centralization" || f.disposition === "waived")
+    return "trust";
+  if (f.class === "bug" && f.verdict === "confirmed" && f.reverified === true && isGreen(f)) {
+    return "exploitable";
+  }
+  return "worth_a_look";
+}
+var URGENT_CONSEQUENCES = new Set(["authority", "code", "value"]);
+
+// client/labels.ts
+var isPrelaunchKey = (id) => id.startsWith("github:") || id.startsWith("gist:");
+function contractName(id) {
+  if (isPrelaunchKey(id))
+    return id.split(":").pop()?.split("/").pop()?.replace(/\.clar$/, "") ?? id;
+  return id.split(".")[1] ?? id;
+}
+
+// client/handoff.ts
+var DEFAULT_FILE = "sentinel-poc.ts";
+var pocFileName = (f) => f.proof?.file ?? DEFAULT_FILE;
+function runCommand(opts) {
+  const lines = [`# save the PoC above as ${opts.file}, then in your own checkout:`];
+  if (opts.commit)
+    lines.push(`git checkout ${opts.commit}   # the commit Sentinel reviewed`);
+  const where = opts.substrate === "fork" ? "needs a Stacks RPC" : "airgapped, no network";
+  lines.push(`bun run ${opts.file}   # @stacks/clarinet-sdk — ${where}`);
+  return lines.join(`
+`);
+}
+function handoffBundle(f, ctx) {
+  const proof = f.proof;
+  const file = pocFileName(f);
+  const poc = proof?.script ? {
+    file,
+    substrate: proof.substrate ?? null,
+    reproduced: !!proof.reproduced,
+    exitCode: proof.exitCode ?? null,
+    source: proof.script
+  } : null;
+  return {
+    contract: ctx.contract,
+    fn: f.targetFn ?? null,
+    commit: ctx.commit ?? null,
+    poc,
+    runCommand: poc ? runCommand({ commit: ctx.commit, file, substrate: poc.substrate }) : null
+  };
+}
+function assertionsOf(output) {
+  const ratio = output.match(/(\d+)\s*\/\s*(\d+)\s*assertions?/i);
+  if (ratio)
+    return `${ratio[1]}/${ratio[2]}`;
+  const passed = output.match(/(\d+)\s*assertions?\s*passed/i);
+  return passed ? `${passed[1]} passed` : null;
+}
+var FENCE = "```";
+var FOOTER = "Sentinel's findings are a starting point for your own review, not an audit sign-off.";
+var KIND_LINE = {
+  exploitable: "Exploitable (verified, re-verified, reproduced in the sandbox)",
+  trust: "Trust assumption (watched: Sentinel alerts when it's used)",
+  worth_a_look: "Worth a look (not proven exploitable)",
+  refuted: "Refuted"
+};
+var tick = (s) => `\`${s}\``;
+var cell = (s) => s.replace(/\|/g, "\\|").replace(/\n/g, " ");
+var num = (n) => n.toLocaleString("en-US");
+function printed(output) {
+  const lines = output.replace(/\[SENTINEL-POC-TRACE\][\s\S]*?\[\/SENTINEL-POC-TRACE\]/g, "").split(`
+`).filter((l) => l.trim());
+  return lines.slice(-40).join(`
+`);
+}
+function movedMd(trace) {
+  const keys = Object.keys(trace.series ?? {}).filter((k) => trace.steps.some((s) => s.values?.[k] !== undefined));
+  const name = (k) => trace.series?.[k] ?? k;
+  const unit = trace.unit ? ` ${trace.unit}` : "";
+  const changes = (i) => {
+    const prev = trace.steps[i - 1]?.values;
+    const now = trace.steps[i].values;
+    if (!prev || !now)
+      return [];
+    return keys.filter((k) => now[k] !== undefined && prev[k] !== undefined && now[k] !== prev[k]).map((k) => `${name(k)} ${num(prev[k])} → ${num(now[k])}${unit}`);
+  };
+  const first = trace.steps.findIndex((_, i) => changes(i).length > 0);
+  const rows = trace.steps.map((s, i) => {
+    const call = [s.call && tick(s.call), s.result && `→ ${tick(s.result)}`].filter(Boolean).join(" ");
+    const start = keys.filter((k) => s.values?.[k] !== undefined).map((k) => `${name(k)} ${num(s.values?.[k])}${unit}`).join(" · ");
+    const change = i === 0 ? start || "start" : changes(i).join(" · ") || "no change";
+    return `| ${i + 1} ${cell(s.label)} | ${cell(call || "—")} | ${cell(change)} |`;
+  });
+  return [
+    "## What the PoC moved",
+    first > 0 ? `**${changes(first).join("; ")} at step ${first + 1} (${trace.steps[first].label}).**` : "No tracked value changed across the steps.",
+    "",
+    "| Step | Call | Value change |",
+    "|---|---|---|",
+    ...rows,
+    ""
+  ];
+}
+function variantOf(f) {
+  if (f.proof?.reproduced)
+    return "reproduced";
+  if (f.proof && !f.proof.unavailable && !f.proof.errored && f.proof.script)
+    return "notrepro";
+  if (f.verdict !== "confirmed")
+    return "lead";
+  return "analysis";
+}
+function where(f, ctx) {
+  const at = ctx.commit ? ` at commit ${tick(ctx.commit.slice(0, 7))}` : "";
+  return f.targetFn ? `Open ${tick(f.targetFn)} in ${tick(contractName(ctx.contract))}${at} and show the function with ~10 lines of context. Point at the lines this finding is about and explain in your own words what they do.` : `Find the code this finding describes in ${tick(contractName(ctx.contract))}${at} and show it with ~10 lines of context. Explain in your own words what it does.`;
+}
+function contextMd(f, ctx, kind) {
+  return [
+    "## Context",
+    `- Contract: ${tick(ctx.contract)}`,
+    ...ctx.commit ? [`- Commit reviewed: ${tick(ctx.commit.slice(0, 7))}`] : [],
+    ...f.targetFn ? [`- Function: ${tick(f.targetFn)}`] : [],
+    `- Kind: ${KIND_LINE[kind]}`
+  ];
+}
+function reportBackMd(ctx, extra) {
+  return [
+    "## How to report back",
+    `- Cite every claim with ${tick("file:line")}${ctx.commit ? ` at commit ${tick(ctx.commit.slice(0, 7))}` : ""}.`,
+    "- Show the code you discuss, quoted from the repo, not paraphrased.",
+    extra,
+    "- Keep two sections: **Facts** (what the code and the run show) and **Assessment** (your conclusions, each with a confidence level). Don't mix them.",
+    "- Don't change contract code until the team has chosen an approach.",
+    ""
+  ];
+}
+function tailMd(ctx, withPoc) {
+  return [
+    "",
+    "## Pull it again",
+    `${FENCE}shell`,
+    `npx @secondlayer/sentinel finding ${ctx.planId} ${ctx.index}${withPoc ? " --poc --run" : ""}`,
+    FENCE,
+    `MCP: ${tick(`get_finding { planId: "${ctx.planId}", index: ${ctx.index} }`)} returns this finding as JSON${withPoc ? ", the PoC source and the run command" : ""}.`,
+    "",
+    "---",
+    FOOTER
+  ];
+}
+function issueMd(f, withCondition) {
+  return [
+    "## The issue",
+    f.headline && f.headline !== f.title ? `${f.headline} (${f.title})` : f.title,
+    ...f.blastRadius ? ["", `**Impact:** ${f.blastRadius}`] : [],
+    ...withCondition && f.precondition ? ["", `**Exploitable when:** ${f.precondition}`] : [],
+    ""
+  ];
+}
+function prelaunchBrief(f, ctx, kind) {
+  const kindLine = kind === "exploitable" ? "Exploitable · look before launch" : kind === "trust" ? "Trust assumption" : "Worth a look before launch";
+  return [
+    "# Task: review a Sentinel finding on pre-launch code",
+    "",
+    `Sentinel found an issue${f.targetFn ? ` in ${tick(f.targetFn)}` : ""}: ${f.title}. PoCs and exploit detail open once Sentinel confirms this code isn't already live on mainnet; possible approaches are shown now, so this brief carries the finding and a direction, not the PoC. Look at the code before launch: the watch arms at launch, but it isn't a substitute for the review.`,
+    "",
+    "## Start here",
+    `1. ${where(f, ctx)}`,
+    "2. Only then discuss approaches that fit this codebase's design.",
+    "",
+    "## How to report back",
+    `- Cite every claim with ${tick("file:line")}${ctx.commit ? ` at commit ${tick(ctx.commit.slice(0, 7))}` : ""}.`,
+    "- Keep **Facts** and **Assessment** apart, with a confidence level on each conclusion.",
+    "",
+    "## Context",
+    `- Contract: ${tick(contractName(ctx.contract))} (pre-launch)${ctx.commit ? `, commit ${tick(ctx.commit.slice(0, 7))}` : ""}`,
+    `- ${f.targetFn ? `Function: ${tick(f.targetFn)} · ` : ""}Kind: ${kindLine}`,
+    "",
+    ...issueMd(f, false),
+    ...f.recommendedAction ? ["## One direction to consider (not a verified patch)", f.recommendedAction, ""] : [],
+    "---",
+    FOOTER
+  ].join(`
+`);
+}
+function trustBrief(f, ctx) {
+  return [
+    "# Task: review a trust assumption and decide whether to reduce it",
+    "",
+    `Sentinel found a power held by design${f.targetFn ? ` in ${tick(f.targetFn)}` : ""}: ${f.title}. It's a trust assumption, not a bug, so there is nothing to reproduce. Review it and decide whether the trust it asks of your users fits your design.`,
+    "",
+    "## Start here",
+    `1. ${where(f, ctx)}`,
+    `2. Find every place that reads what ${f.targetFn ? tick(f.targetFn) : "this power"} changes, and show each one, so the reach of this power is clear.`,
+    "3. Only then discuss options that fit this codebase's design.",
+    "",
+    ...reportBackMd(ctx, "- There is no PoC for a trust assumption. Don't write an exploit for it."),
+    ...contextMd(f, ctx, "trust"),
+    "- Class: trust assumption (a power held by design)",
+    "- Evidence: checked by Sentinel's adversarial verifier. No PoC; nothing to run.",
+    "",
+    "## What it is",
+    f.headline && f.headline !== f.title ? `${f.headline} (${f.title})` : f.title,
+    ...f.powers?.length ? [
+      "",
+      "**Powers:**",
+      ...f.powers.map((p) => `- ${p.holder} can ${p.can}${p.fn ? ` (${tick(p.fn)})` : ""}`)
+    ] : [],
+    ...f.blastRadius ? ["", `**Impact:** ${f.blastRadius}`] : [],
+    ...f.precondition ? ["", `**Usable when:** ${f.precondition}`] : [],
+    "",
+    ...f.recommendedAction ? ["## Options to consider (not a patch)", `- ${f.recommendedAction}`, ""] : [],
+    "## If you change it",
+    "- A test for the new behavior.",
+    "- A test that an account without the role is still refused.",
+    ...tailMd(ctx, false)
+  ].join(`
+`);
+}
+function refutedBrief(f, ctx) {
+  return [
+    "# Note: a Sentinel finding refuted on re-check",
+    "",
+    `Sentinel's verifier re-examined this${f.targetFn ? ` (${tick(f.targetFn)})` : ""} and showed it can't happen: ${f.title}. It's kept for the record and isn't watched.`,
+    "",
+    ...contextMd(f, ctx, "refuted"),
+    ...tailMd(ctx, false)
+  ].join(`
+`);
+}
+function bugBrief(f, ctx, kind) {
+  const v = variantOf(f);
+  const bundle = handoffBundle(f, { contract: ctx.contract, commit: ctx.commit });
+  const poc = bundle.poc;
+  const p = f.proof;
+  const asserted = p?.output ? assertionsOf(p.output) : null;
+  const counted = asserted?.includes("/") ? `${asserted} assertions, ` : asserted ? `${asserted.replace(" passed", "")} assertions passed, ` : "";
+  const ran = `${counted}exit ${p?.exitCode ?? "?"}`;
+  const sandbox = p?.substrate === "fork" ? "a mainnet-fork sandbox" : `an airgapped sandbox (${tick("--network none")})`;
+  const what = `Sentinel found an issue${f.targetFn ? ` in ${tick(f.targetFn)}` : ""}: ${f.title}`;
+  const open = {
+    reproduced: `${what}. It reproduced with the PoC below. Review the affected code, choose an approach that fits your design, then confirm the PoC no longer succeeds.`,
+    notrepro: `${what}. Its verifier confirmed it by analysis, but the PoC below ran and did not reproduce it. Review the affected code and the run, and decide whether it applies to your deployment.`,
+    analysis: `${what}. Its verifier confirmed it by analysis; no PoC result yet. ${poc ? "Run the PoC below in your own tooling, then review" : "Review"} the affected code and choose an approach that fits your design.`,
+    lead: `An auditor flagged an issue${f.targetFn ? ` in ${tick(f.targetFn)}` : ""}: ${f.title}. The verifier hasn't confirmed it, so treat it as a lead.`
+  }[v];
+  const evidence = {
+    reproduced: `confirmed by Sentinel's adversarial verifier${f.reverified ? ", re-verified by a second independent pass" : ""}, then reproduced in ${sandbox}: ${ran}.${f.reverified ? "" : " Not re-verified yet."}`,
+    notrepro: `confirmed by Sentinel's adversarial verifier. The PoC ran in ${sandbox} and did not reproduce it (${ran}). Verified by analysis only.`,
+    analysis: "confirmed by Sentinel's adversarial verifier. No PoC result yet.",
+    lead: "found by an auditor, not yet confirmed by the verifier. Treat it as a lead."
+  }[v];
+  const runStep = poc ? v === "notrepro" ? `2. Save the PoC below as ${tick(poc.file)} and run it. Show the output, compare it with Sentinel's run below, and say whether it reproduces in this codebase.` : v === "reproduced" ? `2. Save the PoC below as ${tick(poc.file)} and run it. Show the output and say whether it reproduces.` : `2. Save the PoC below as ${tick(poc.file)} and run it. Show the output and say whether it reproduces. If its setup doesn't match this codebase, adapt it and list what you changed.` : null;
+  const out = p?.output ? printed(p.output) : "";
+  return [
+    "# Task: investigate a Sentinel finding and decide on an approach",
+    "",
+    `${open}${poc ? " Simnet only; nothing touches mainnet." : ""}`,
+    "",
+    "## Start here",
+    `1. ${where(f, ctx)}`,
+    ...runStep ? [runStep] : [],
+    `${runStep ? 3 : 2}. Only then discuss approaches that fit this codebase's design.`,
+    "",
+    ...reportBackMd(ctx, poc ? "- Show the exact command you ran and its full output." : "- Say what you checked and how."),
+    ...contextMd(f, ctx, kind),
+    f.class === "bug" ? "- Class: bug (not a trust assumption; no privileged role needed)" : `- Class: ${f.class}`,
+    `- Evidence: ${evidence}`,
+    "",
+    ...v === "reproduced" && p?.trace ? movedMd(p.trace) : [],
+    ...issueMd(f, true),
+    ...poc ? [
+      v === "notrepro" ? `## PoC as it ran (save as ${tick(poc.file)})` : `## PoC (save as ${tick(poc.file)})`,
+      `${FENCE}typescript`,
+      poc.source,
+      FENCE,
+      "",
+      "## Run it",
+      `${FENCE}shell`,
+      bundle.runCommand ?? "",
+      FENCE,
+      ...out && (v === "reproduced" || v === "notrepro") ? [
+        v === "reproduced" ? "Sentinel's output, before any change:" : "Sentinel's run printed:",
+        FENCE,
+        out,
+        FENCE
+      ] : [],
+      ""
+    ] : [],
+    ...f.recommendedAction ? ["## One direction to consider (not a verified patch)", f.recommendedAction, ""] : [],
+    ...poc ? [
+      "## Confirm a change",
+      "- Re-run the PoC. With your change in place it should no longer succeed.",
+      "- Consider keeping the PoC as a regression test, with its assertions flipped to expect the failure."
+    ] : [],
+    ...tailMd(ctx, !!poc)
+  ].join(`
+`);
+}
+function agentBrief(f, ctx) {
+  const kind = f.kind ?? findingKind(f);
+  if (ctx.prelaunch && kind !== "refuted")
+    return prelaunchBrief(f, ctx, kind);
+  if (kind === "refuted")
+    return refutedBrief(f, ctx);
+  if (kind === "trust")
+    return trustBrief(f, ctx);
+  return bugBrief(f, ctx, kind);
+}
+
 // mcp/server.ts
 var CLAIMED_NOTE = "Exploit detail is hidden until you verify control of this contract in the web app.";
 var REVERIFY_ESTIMATE = "about 10 min";
@@ -20326,14 +20638,19 @@ var paidRun = (willDo) => ({
   cost: PAID_RUN_NOTE,
   next: NEXT
 });
-function subjectView(g) {
-  const status = subjectStatus(g.watches);
+function intentView(i) {
+  const lead = i.rows[0];
   return {
-    subject: g.name,
-    kind: [...new Set(g.watches.map((w) => kindTag(w.rule)))],
-    status,
-    mutedUntil: g.watches.map((w) => mutedUntilOf(w)).find(Boolean) ?? null,
-    rules: g.watches.map((w) => ({
+    watch: i.title,
+    subject: lead ? subjectName(lead.subject, lead.units) : i.title,
+    kind: i.kind,
+    on: i.on,
+    alertLevel: i.alertLevel,
+    summary: intentLine(i),
+    members: i.members,
+    status: subjectStatus(i.rows),
+    mutedUntil: i.rows.map((w) => mutedUntilOf(w)).find(Boolean) ?? null,
+    rules: i.rows.map((w) => ({
       watchId: w.id,
       kind: w.rule.kind,
       status: w.status,
@@ -20373,7 +20690,7 @@ function buildTools(client) {
       }))
     },
     get_plan: {
-      description: "A monitoring plan: verdict, findings (title, headline, severity, class, verdict, disposition) and watches.",
+      description: "A monitoring plan: verdict, findings (title, headline, severity, class, verdict, disposition, kind, alertLevel) and watches.",
       input: { planId },
       run: async (a) => {
         const p = await client.plan(a.planId);
@@ -20396,21 +20713,32 @@ function buildTools(client) {
             severity: f.severity,
             class: f.class,
             verdict: f.verdict,
-            disposition: f.disposition
+            disposition: f.disposition,
+            kind: f.kind,
+            alertLevel: f.alertLevel
           })),
           watches: p.report?.plan?.watches ?? []
         };
       }
     },
     get_finding: {
-      description: "One finding in full, including proof and the verifier's note when you are a verified owner.",
+      description: "One finding in full (its kind and its watch's alert level) plus the handoff: the agent brief (the finding page's \"Copy agent brief\", a Markdown task to start your own review from), the stored PoC source and the exact command to re-run it against the reviewed source (the same as `sentinel finding --brief --poc --run`). Proof and the verifier's note need a verified owner.",
       input: { planId, index: number2().int().min(0).describe("Finding index from get_plan") },
       run: async (a) => {
         const [finding, p] = await Promise.all([
           client.finding(a.planId, a.index),
           client.plan(a.planId)
         ]);
-        return { ...noteFor(p), finding };
+        const commit = p.report?.target?.commit ?? null;
+        const bundle = handoffBundle(finding, { contract: p.contractId, commit });
+        const brief = p.access === "claimed" ? null : agentBrief(finding, {
+          contract: p.contractId,
+          commit,
+          planId: a.planId,
+          index: a.index,
+          prelaunch: p.access === "prelaunch"
+        });
+        return { ...noteFor(p), finding, brief, poc: bundle.poc, runCommand: bundle.runCommand };
       }
     },
     get_run_status: {
@@ -20529,13 +20857,13 @@ function buildTools(client) {
       run: async (a) => a.confirm === true ? client.testsFromRepo(a.planId) : paidRun("Run the Clarinet suite from this pre-launch plan's repo in the airgapped sandbox.")
     },
     list_watches: {
-      description: "What a plan watches, by subject (a function or a token): kind, status, each rule in token units, and any mute.",
+      description: "What a plan watches, as intent watches (Money out per token, Control changes, one per finding, the fns you added): on or off, the threshold or summary, the fns covered, each rule in token units, any mute, and the subject name the other watch tools take.",
       input: { planId },
       run: async (a) => {
         const ctx = await watchContext(client, a.planId);
         return {
           ...ctx.access === "claimed" ? { note: CLAIMED_NOTE } : {},
-          subjects: groupSubjects(ctx.watches).map(subjectView)
+          watches: ctx.intents.map(intentView)
         };
       }
     },
@@ -20713,7 +21041,7 @@ async function runTool(tool, args) {
   }
 }
 function buildServer(client) {
-  const server = new McpServer({ name: "sentinel", version: "0.1.1" });
+  const server = new McpServer({ name: "sentinel", version: "0.2.0" });
   for (const [name, tool] of Object.entries(buildTools(client))) {
     server.registerTool(name, { description: tool.description, inputSchema: tool.input }, (args) => runTool(tool, args));
   }

package/dist/sentinel-client.d.ts

@@ -2,6 +2,7 @@
  * Client for the Sentinel v1 API (docs/api.md). Shared by the MCP server and the CLI. No dependencies:
  * global fetch. Auth is one function, `authHeader`, so another credential can be swapped in later.
  */
+import type { AlertLevel, FindingKind } from "./kind";
 export declare const DEFAULT_BASE_URL = "https://api.runsentinel.app";
 export declare class SentinelError extends Error {
     readonly status: number;
@@ -47,8 +48,25 @@ export type Finding = {
     verdict: string;
     disposition: string;
     poc?: string;
+    /** What the finding is for the people watching (client/kind.ts), stamped by the API. */
+    kind?: FindingKind;
+    /** How the finding's watch pages; absent on a refuted finding. */
+    alertLevel?: AlertLevel;
+    reverified?: boolean;
+    /** "fn" when `targetFn` names the function; "contract" when no single function carries it. */
+    scope?: "fn" | "contract";
+    /** Trust findings: the powers held by design, one entry each. */
+    powers?: Power[];
+    /** The watch row's subject, a short fn-level phrase (verified owners only). */
+    watchSubject?: string;
     [field: string]: unknown;
 };
+/** One power a trust finding describes (monitoring/adjudication.ts `Power`, copied: no deps). */
+export type Power = {
+    holder: string;
+    can: string;
+    fn?: string;
+};
 /** A plan at the caller's access level: `access` is absent on the teaser. */
 export type PlanView = {
     view: string;
@@ -114,6 +132,11 @@ export type WatchSubject = {
 } | {
     kind: "asset";
     asset: string;
+}
+/** Control changes: one group over every fn that changes who controls the contract. */
+ | {
+    kind: "group";
+    group: "control";
 };
 export type WatchStatus = "suggested" | "live" | "paused";
 export type Units = {
@@ -146,8 +169,57 @@ export type StoredWatch = {
     updatedAt: string;
     units: Units | null;
 };
+export type IntentKind = "money_out" | "control" | "finding" | "owner_fn";
+/**
+ * One intent watch: what a team sees (Money out per asset, Control changes, one per finding, a fn the team
+ * added). `rows` are the stored watches behind it: what a rule edit, a switch or a mute acts on.
+ */
+export type IntentWatch<R = StoredWatch & {
+    on: boolean;
+}> = {
+    id: string;
+    kind: IntentKind;
+    title: string;
+    tag: string;
+    summary: string;
+    on: boolean;
+    alertLevel: "urgent" | "normal";
+    watchIds: string[];
+    rows: R[];
+    members: {
+        group: string;
+        fns: string[];
+    }[];
+    /** Money out: the asset, its token units and its threshold (null amount: every outflow alerts). */
+    asset?: string;
+    units?: Units | null;
+    threshold?: {
+        amount: string | null;
+        basis: string;
+        confirmed: boolean;
+        suggested: {
+            amount: string;
+            basis: string;
+        } | null;
+    };
+    findingRef?: {
+        title: string;
+        index: number | null;
+    };
+};
+/** The stored rows behind a list of intent watches, in order. */
+export declare const rowsOf: <R>(intents: {
+    rows: R[];
+}[]) => R[];
 export type WatchesView = {
-    watches: StoredWatch[];
+    intents: IntentWatch[];
+    /** "N of M on", over intent watches. */
+    counts: {
+        on: number;
+        total: number;
+    };
+    /** Finding-based watches hidden until the account verifies control (a count only). */
+    locked: number;
     events: {
         id: string;
         watchId: string;
@@ -167,13 +239,13 @@ export type StartedMonitoring = {
     contractId: string;
     planId: string;
     status: "draft" | "requested" | "live";
-    watches: StoredWatchView[];
+    intents: IntentWatch<StoredWatchView>[];
     webhookUrl: string | null;
     slackUrl: string | null;
     emailAlerts: boolean;
     hasSigningSecret: boolean;
 };
-type StoredWatchView = Pick<StoredWatch, "id" | "subject" | "rule" | "status" | "title">;
+type StoredWatchView = Pick<StoredWatch, "id" | "subject" | "rule" | "suggestedRule" | "delivery" | "provenance" | "status" | "title" | "reason" | "units">;
 export type WatchChoice = {
     watchId?: string;
     fn: string;
@@ -200,7 +272,8 @@ export type DeliveryResult = {
     detail: string;
 };
 export declare const subjectKey: (s: WatchSubject) => string;
-/** The subject's display name: the fn name, or the token's symbol (never the raw token id). */
+export declare const CONTROL_NAME = "Control changes";
+/** The subject's display name: the fn name, the token's symbol (never the raw token id), or the group's. */
 export declare function subjectName(s: WatchSubject, units: Units | null): string;
 type HasSubject = {
     subject: WatchSubject;
@@ -220,7 +293,8 @@ export declare class SubjectError extends Error {
 export declare function groupSubjects<W extends HasSubject>(watches: W[]): SubjectMatch<W>[];
 /**
  * The watches on the subject `name` points at: its display name (fn name, token symbol, or the part
- * after `::`), its subjectKey (`fn:…` / `asset:…`) or a full asset id, case-insensitive. A name that
+ * after `::`, or "Control changes" / "control"), its subjectKey (`fn:…` / `asset:…` / `group:control`) or a
+ * full asset id, case-insensitive. A name that
  * matches nothing, or more than one subject, throws a SubjectError listing the candidates.
  */
 export declare function resolveSubject<W extends HasSubject>(watches: W[], name: string): SubjectMatch<W>;
@@ -231,6 +305,8 @@ export declare function ruleSummary(rule: WatchRule, units: Units | null): strin
 export type WatchKindTag = "finding" | "outflow" | "who-acts" | "governance" | "upgrade";
 /** The plain tag a rule is listed under. */
 export declare function kindTag(rule: WatchRule): WatchKindTag;
+/** An intent watch's one line: a Money out threshold in token units (or its fail-safe), else its summary. */
+export declare function intentLine(i: Pick<IntentWatch<unknown>, "kind" | "summary" | "threshold" | "units">): string;
 /** A subject's status from its rules: live if any is, else paused if all are, else suggested. */
 export declare function subjectStatus(ws: {
     status: WatchStatus;
@@ -355,7 +431,11 @@ export type WatchContext = {
     contractId: string;
     /** The plan's access level for this caller; a claimed one hides exploit detail. */
     access: PlanView["access"];
-    watches: StoredWatch[];
+    intents: IntentWatch[];
+    /** The stored rows behind the intents: what subjects resolve over. */
+    watches: (StoredWatch & {
+        on: boolean;
+    })[];
 };
 /** The caller's watches for a plan. */
 export declare function watchContext(client: SentinelClient, planId: string): Promise<WatchContext>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secondlayer/sentinel",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Sentinel from a terminal or an agent: the CLI, an MCP server and a client for your Stacks contract monitoring.",
   "license": "MIT",
   "repository": "https://runsentinel.app/docs",