@secondlayer/sentinel 0.1.0

package/dist/cli.js

@@ -0,0 +1,919 @@
+#!/usr/bin/env node
+
+// cli/main.ts
+import { createInterface } from "node:readline/promises";
+
+// client/credentials.ts
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var CREDITS_API_URL = "https://api.secondlayer.tools";
+var creditsUrl = () => (process.env.SL_CREDITS_API_URL ?? CREDITS_API_URL).replace(/\/+$/, "");
+var dir = () => join(process.env.HOME || homedir(), ".secondlayer");
+var sessionPath = () => join(dir(), "session.json");
+var tokenFilePath = () => join(dir(), "sentinel.json");
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function writePrivate(path, data) {
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = join(dirname(path), `.${process.pid}.tmp`);
+  await writeFile(tmp, `${JSON.stringify(data, null, 2)}
+`, { mode: 384, encoding: "utf8" });
+  await chmod(tmp, 384);
+  await rename(tmp, path);
+}
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isSession = (v) => isRecord(v) && typeof v.token === "string" && v.token !== "" && typeof v.email === "string";
+async function readSessionFile() {
+  const raw = await readJson(sessionPath());
+  if (isRecord(raw) && isRecord(raw.sessions))
+    return { sessions: raw.sessions };
+  if (isSession(raw))
+    return { sessions: { [CREDITS_API_URL]: raw } };
+  return { sessions: {} };
+}
+async function readSession(url = creditsUrl()) {
+  const s = (await readSessionFile()).sessions[url.replace(/\/+$/, "")];
+  return isSession(s) ? s : null;
+}
+async function writeSession(session, url = creditsUrl()) {
+  const file = await readSessionFile();
+  file.sessions[url.replace(/\/+$/, "")] = session;
+  await writePrivate(sessionPath(), file);
+}
+async function clearSession(url = creditsUrl()) {
+  const file = await readSessionFile();
+  delete file.sessions[url.replace(/\/+$/, "")];
+  if (Object.keys(file.sessions).length === 0)
+    await rm(sessionPath(), { force: true });
+  else
+    await writePrivate(sessionPath(), file);
+}
+async function readTokenFile() {
+  const raw = await readJson(tokenFilePath());
+  return isRecord(raw) && typeof raw.token === "string" && raw.token !== "" ? { token: raw.token, email: typeof raw.email === "string" ? raw.email : undefined } : null;
+}
+var writeTokenFile = (file) => writePrivate(tokenFilePath(), file);
+var clearTokenFile = () => rm(tokenFilePath(), { force: true });
+async function resolveToken(flag) {
+  const env = process.env.SENTINEL_API_KEY;
+  if (env)
+    return { token: env, source: "env" };
+  if (flag)
+    return { token: flag, source: "flag" };
+  const file = await readTokenFile();
+  if (file)
+    return { token: file.token, source: "token file" };
+  const session = await readSession();
+  return session ? { token: session.token, source: "secondlayer session" } : null;
+}
+var NOT_LOGGED_IN = "Not logged in. Run: sentinel login";
+
+// client/sentinel-client.ts
+var DEFAULT_BASE_URL = "https://api.runsentinel.app";
+
+class SentinelError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "SentinelError";
+  }
+}
+var subjectKey = (s) => s.kind === "fn" ? `fn:${s.fn}` : `asset:${s.asset}`;
+function subjectName(s, units) {
+  if (s.kind === "fn")
+    return s.fn;
+  if (units?.symbol)
+    return units.symbol;
+  if (s.asset.toLowerCase() === "stx")
+    return "STX";
+  return s.asset.split("::")[1] ?? s.asset;
+}
+
+class SubjectError extends Error {
+  candidates;
+  constructor(message, candidates) {
+    super(message);
+    this.candidates = candidates;
+    this.name = "SubjectError";
+  }
+}
+function groupSubjects(watches) {
+  const out = new Map;
+  for (const w of watches) {
+    const key = subjectKey(w.subject);
+    const g = out.get(key) ?? { key, name: subjectName(w.subject, w.units), watches: [] };
+    g.watches.push(w);
+    out.set(key, g);
+  }
+  return [...out.values()];
+}
+function resolveSubject(watches, name) {
+  const groups = groupSubjects(watches);
+  const q = name.trim().toLowerCase();
+  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;
+  });
+  if (hits.length === 1)
+    return hits[0];
+  if (hits.length === 0) {
+    const names = groups.map((g) => g.name);
+    throw new SubjectError(`No watched subject called "${name}". Watched: ${names.join(", ") || "nothing yet"}`, names);
+  }
+  const names = hits.map((g) => g.key);
+  throw new SubjectError(`"${name}" matches more than one subject: ${names.join(", ")}`, names);
+}
+var group = (digits) => digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+function toUnits(base, decimals) {
+  if (!/^\d+$/.test(base))
+    return base;
+  const digits = base.replace(/^0+(?=\d)/, "");
+  if (decimals === 0)
+    return group(digits);
+  const padded = digits.padStart(decimals + 1, "0");
+  const whole = padded.slice(0, padded.length - decimals);
+  const frac = padded.slice(padded.length - decimals).replace(/0+$/, "");
+  return frac ? `${group(whole)}.${frac}` : group(whole);
+}
+function amountText(base, units) {
+  return units ? `${toUnits(base, units.decimals)} ${units.symbol}` : `${group(base)} base units`;
+}
+var WINDOWS = { 720: "1 hour", 4320: "6 hours", 17280: "1 day" };
+var windowText = (blocks) => WINDOWS[blocks] ?? `${blocks.toLocaleString("en-US")} blocks`;
+function ruleSummary(rule, units) {
+  switch (rule.kind) {
+    case "signature":
+      return `verified finding: ${rule.findingTitle}`;
+    case "audit":
+      return rule.triggerClass === "governance.proposal_submitted" ? "reviews each governance proposal" : "reviews each upgrade";
+    case "callerAllowlist":
+      return rule.allow.length ? `any call from outside ${rule.allow.length} allowed principal(s)` : "any call";
+    case "outflowSingle":
+      return rule.amount ? `a single outflow of ${amountText(rule.amount, units)} or more` : "every outflow";
+    case "outflowWindow":
+      return `${amountText(rule.amount, units)} or more out within ${windowText(rule.blocks)}`;
+    case "valueNewActor":
+      return `${amountText(rule.amount, units)} or more to or from a new actor`;
+    case "actor": {
+      const names = {
+        newCaller: "a new caller",
+        firstCall: "a first call",
+        roleChange: "a role change"
+      };
+      return `${rule.signals.map((x) => names[x]).join(", ")}${rule.allow.length ? ` (outside ${rule.allow.length} allowed)` : ""}`;
+    }
+  }
+}
+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 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";
+}
+var isMutableRule = (rule) => rule.kind !== "signature" && rule.kind !== "audit";
+function mutedUntilOf(w, now = Date.now()) {
+  const at = w.delivery.mutedUntil;
+  return at && Date.parse(at) > now ? at : null;
+}
+function createClient(opts) {
+  const baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const doFetch = opts.fetch ?? globalThis.fetch;
+  const authHeader = () => ({ authorization: `Bearer ${opts.token}` });
+  async function call(method, path, body) {
+    const res = await doFetch(`${baseUrl}${path}`, {
+      method,
+      headers: {
+        ...authHeader(),
+        ...body === undefined ? {} : { "content-type": "application/json" }
+      },
+      body: body === undefined ? undefined : JSON.stringify(body)
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok)
+      throw new SentinelError(res.status, data?.error ?? `HTTP ${res.status}`);
+    return data;
+  }
+  const plan = (id) => `/v1/plans/${encodeURIComponent(id)}`;
+  const appPlan = (id) => `/plan/${encodeURIComponent(id)}`;
+  return {
+    me: () => call("GET", "/v1/me"),
+    plans: async () => (await call("GET", "/v1/plans")).plans,
+    plan: (id) => call("GET", plan(id)),
+    finding: (id, n) => call("GET", `${plan(id)}/findings/${n}`),
+    runs: async (id) => (await call("GET", `${plan(id)}/runs`)).runs,
+    alerts: async (contract) => (await call("GET", contract ? `/v1/alerts?contract=${encodeURIComponent(contract)}` : "/v1/alerts")).alerts,
+    reverify: (id) => call("POST", `/plan/${encodeURIComponent(id)}/reverify`),
+    reproduce: (id, finding) => call("POST", `/plan/${encodeURIComponent(id)}/reproduce`, { finding }),
+    challenge: (id, finding, reason) => call("POST", `${appPlan(id)}/challenge`, { finding, reason }),
+    replay: (id, finding) => call("POST", `${appPlan(id)}/replay`, { finding }),
+    directed: (id, prompt) => call("POST", `${appPlan(id)}/directed`, { prompt }),
+    testsFromRepo: (id) => call("POST", `${appPlan(id)}/tests`, { fromRepo: true }),
+    previewPlan: (contractId) => call("POST", "/plan/preview", { contractId }),
+    createPlan: (contractId) => call("POST", "/plan", { contractId }),
+    billing: () => call("GET", "/billing"),
+    watches: (planId) => call("GET", `${appPlan(planId)}/watches`),
+    setRule: (planId, watchId, rule) => call("POST", `${appPlan(planId)}/watches/${encodeURIComponent(watchId)}/rule`, { rule }),
+    addRule: (planId, subject, rule) => call("POST", `${appPlan(planId)}/watches`, { subject, rule }),
+    setWatches: (planId, watchIds, on) => call("POST", `${appPlan(planId)}/watches/state`, {
+      watchIds,
+      on
+    }),
+    mute: (planId, watchId, mutedUntil) => call("POST", `${appPlan(planId)}/watches/${encodeURIComponent(watchId)}/delivery`, { mutedUntil }),
+    muteAlert: (alertId, hours) => call("POST", `/alerts/${encodeURIComponent(alertId)}/mute`, { hours }),
+    parseRule: (planId, subject, text) => call("POST", `${appPlan(planId)}/rules/parse`, { subject, text }),
+    monitorSettings: (planId, settings) => call("POST", `${appPlan(planId)}/monitor`, settings),
+    testAlert: (planId, dest = {}) => call("POST", `${appPlan(planId)}/testalert`, dest),
+    watchContract: (contractId) => call("POST", "/contracts/watch", {
+      contractId
+    }),
+    stopMonitoring: (planId) => call("DELETE", `${appPlan(planId)}/monitor`)
+  };
+}
+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);
+  return {
+    planId,
+    contractId: plan.contractId,
+    access: plan.access,
+    watches: (await client.watches(planId)).watches
+  };
+}
+async function savedMonitor(client, planId) {
+  const m = (await client.plan(planId)).monitor;
+  if (!m?.status)
+    throw new SentinelError(409, "Turn monitoring on first.");
+  return m;
+}
+var savedChoices = async (client, planId) => (await savedMonitor(client, planId)).watches;
+async function planOfContract(client, contractId) {
+  const me = await client.me();
+  const hit = [...me.watching ?? [], ...me.claims ?? []].find((c) => c.contractId === contractId);
+  if (!hit)
+    throw new SentinelError(404, `You aren't monitoring ${contractId}.`);
+  return hit.planId;
+}
+
+// cli/auth.ts
+var sessionExpiry = () => new Date(Date.now() + 90 * 24 * 60 * 60 * 1000).toISOString();
+async function post(doFetch, path, body) {
+  try {
+    const res = await doFetch(`${creditsUrl()}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok)
+      return { ok: false, error: data?.error ?? data?.message ?? `HTTP ${res.status}` };
+    return { ok: true, data };
+  } catch (e) {
+    return { ok: false, error: `Couldn't reach ${creditsUrl()}: ${e.message}` };
+  }
+}
+async function check(client) {
+  try {
+    const me = await client.me();
+    return { email: me.user?.email ?? null };
+  } catch (e) {
+    if (e instanceof SentinelError)
+      return { error: e.message, status: e.status };
+    return { error: e.message, status: 0 };
+  }
+}
+async function login(flags, io) {
+  const { auth } = io;
+  if (flags.includes("--with-token")) {
+    const token = (await auth.readStdin()).trim();
+    if (!token) {
+      io.err('No token on stdin. Usage: echo "$KEY" | sentinel login --with-token');
+      return 1;
+    }
+    const r = await check(auth.clientFor(token));
+    if ("error" in r) {
+      io.err(`Token rejected: ${r.error}`);
+      return 1;
+    }
+    await writeTokenFile({ token, email: r.email ?? undefined });
+    io.out(`Logged in${r.email ? ` as ${r.email}` : ""}.`);
+    return 0;
+  }
+  const existing = await readSession();
+  if (existing && !flags.includes("--force")) {
+    io.out(`Already logged in as ${existing.email}. Run again with --force to switch accounts.`);
+    return 0;
+  }
+  const doFetch = auth.fetch ?? globalThis.fetch;
+  const email = (await auth.prompt("Email: ")).trim();
+  if (!/^.+@.+\..+$/.test(email)) {
+    io.err("Invalid email");
+    return 1;
+  }
+  const sent = await post(doFetch, "/api/auth/magic-link", { email });
+  if (!sent.ok) {
+    io.err(sent.error);
+    return 1;
+  }
+  io.out("Check your inbox for a 6-digit code.");
+  if (sent.data.code)
+    io.out(`(DEV_MODE code: ${sent.data.code})`);
+  const code = (await auth.prompt("Code: ")).trim();
+  if (!/^\d{6}$/.test(code)) {
+    io.err("Expected 6 digits");
+    return 1;
+  }
+  const verified = await post(doFetch, "/api/auth/verify", { email, code });
+  if (!verified.ok) {
+    io.err(verified.error);
+    return 1;
+  }
+  const { sessionToken, account } = verified.data;
+  await writeSession({
+    token: sessionToken,
+    email: account.email,
+    accountId: account.id,
+    expiresAt: sessionExpiry()
+  });
+  io.out(`Logged in as ${account.email}`);
+  const r = await check(auth.clientFor(sessionToken));
+  if ("error" in r) {
+    io.err(r.error);
+    return r.status === 403 ? 0 : 1;
+  }
+  return 0;
+}
+async function logout(io) {
+  await clearTokenFile();
+  await clearSession();
+  io.out("Logged out.");
+  io.out(`This also signs the secondlayer CLI out of ${creditsUrl()}.`);
+  return 0;
+}
+async function whoami(client, io) {
+  const r = await check(client);
+  if ("error" in r) {
+    io.err(r.error);
+    return 1;
+  }
+  io.out(`${r.email ?? "signed in"} (${io.auth.source ?? "unknown credential"})`);
+  return 0;
+}
+
+// cli/sentinel.ts
+var USAGE = `sentinel <command>
+
+  login [--force]             sign in with your secondlayer account (email, then a 6-digit code)
+  login --with-token          read an API key from stdin (CI); checked before it is saved
+  logout                      forget the saved login (also signs the secondlayer CLI out)
+  whoami                      who you are and where the credential came from
+  new <contract> [--yes]      plan a contract: see what it would do and cost; --yes starts it
+  balance                     your balance and what a plan, a deep run and a monitored event cost
+  alerts [--contract <id>]    your alerts, newest first
+
+  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
+  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
+
+paid runs on a plan you own (each starts only with --yes; without it you see what it would do):
+  reproduce <plan> <n> [--yes]               write and run a PoC for finding n in the sandbox
+  challenge <plan> <n> "<reason>" [--yes]    re-verify finding n against your argument
+  replay <plan> <n> [--yes]                  re-run finding n's stored PoC
+  directed <plan> "<what to watch>" [--yes]  re-plan around what you want watched
+  tests <plan> --from-repo [--yes]           run the Clarinet suite from a pre-launch plan's repo
+
+A key needs Plans & findings (read for the above, write for new and the runs above); monitoring commands need Monitoring
+(read to look, write to change); mute-alert needs Alerts: write.
+
+monitoring (a write only happens with --yes; without it you see what would change):
+  watches <plan> [--json]                        subjects, rules, status, mutes
+  rule <plan> <subject> "<sentence>" [--yes]     read the sentence; --yes adds or edits the rules it found
+  watch on|off <plan> <subject> [--yes]          on and off apply now
+  mute <plan> <subject> [1h|24h|7d] [--yes]      default 24h
+  unmute <plan> <subject> [--yes]
+  mute-alert <alert> [1h|24h|7d] [--yes]         mute the watch behind an alert
+  destinations <plan> [--email on|off] [--webhook URL] [--slack URL] [--yes]
+                                                 with no options: where alerts go now ("" clears a URL)
+  test-alert <plan> [--yes]                      a sample alert to every saved destination
+  follow <contract> [--yes]                      start monitoring a deployed contract
+  unfollow <contract> [--yes]
+
+<subject> is a function name or a token symbol, as the watches command shows it.
+
+credential: SENTINEL_API_KEY, then --token <key>, then sentinel login. env: SENTINEL_API_URL
+`;
+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 table = (rows) => {
+  const text = rows.map((r) => r.map((c) => cell(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());
+};
+var phaseOf = (r) => {
+  const last = r.events.at(-1);
+  return last ? [last.name ?? last.kind, last.state].filter(Boolean).join(" ") : "starting";
+};
+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;
+};
+async function run(argv, io) {
+  const flags = [];
+  const args = [];
+  const values = {};
+  const usage = (msg) => {
+    io.err(msg ? `${msg}
+
+${USAGE}` : USAGE);
+    return 2;
+  };
+  for (let i = 0;i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--"))
+      args.push(a);
+    else if (VALUE_FLAGS.has(a)) {
+      if (i + 1 >= argv.length)
+        return usage(`${a} needs a value`);
+      values[a] = argv[++i];
+    } else
+      flags.push(a);
+  }
+  const [cmd, id, n] = args;
+  const json = flags.includes("--json");
+  const known = new Set(["--json", "--yes", "--help", "--force", "--with-token", "--from-repo"]);
+  if (flags.some((f) => !known.has(f)))
+    return usage(`Unknown flag ${flags.find((f) => !known.has(f))}`);
+  if (flags.includes("--help") || !cmd || cmd === "help") {
+    io.out(USAGE);
+    return cmd || flags.includes("--help") ? 0 : 2;
+  }
+  const needId = () => id ? null : usage(`sentinel ${cmd} needs a plan id`);
+  try {
+    switch (cmd) {
+      case "plans": {
+        const plans = await io.client.plans();
+        if (json)
+          io.out(JSON.stringify(plans, null, 2));
+        else {
+          const rows = plans.map((p) => [
+            p.contractId,
+            cell(p.monitoring, "none"),
+            p.evidence?.worst ? `${p.evidence.worst.severity} ${p.evidence.worst.evidence}` : null,
+            p.planId
+          ]);
+          for (const l of table([["CONTRACT", "MONITORING", "WORST", "PLAN"], ...rows]))
+            io.out(l);
+        }
+        return 0;
+      }
+      case "plan": {
+        const bad = needId();
+        if (bad !== null)
+          return bad;
+        const p = await io.client.plan(id);
+        if (json) {
+          io.out(JSON.stringify(p, null, 2));
+          return 0;
+        }
+        io.out(verdictLine(p));
+        if (p.access === "claimed")
+          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.verdict,
+          f.disposition,
+          f.title
+        ]);
+        for (const l of table(rows))
+          io.out(l);
+        return 0;
+      }
+      case "finding": {
+        const bad = needId();
+        if (bad !== null)
+          return bad;
+        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));
+        if (json) {
+          io.out(JSON.stringify(f, null, 2));
+          return 0;
+        }
+        io.out(`${f.title}
+${[f.severity, f.class, f.verdict, f.disposition].map((v) => cell(v)).join(" ")}`);
+        if (f.headline)
+          io.out(f.headline);
+        return 0;
+      }
+      case "runs": {
+        const bad = needId();
+        if (bad !== null)
+          return bad;
+        const runs = await io.client.runs(id);
+        for (const l of table(runs.map((r) => [
+          r.id,
+          r.kind,
+          r.status,
+          r.status === "running" ? phaseOf(r) : r.finishedAt ?? ""
+        ])))
+          io.out(l);
+        return 0;
+      }
+      case "watch": {
+        if (id === "on" || id === "off") {
+          return await monitoring("watch", args.slice(2), id === "on", flags, values, io, usage);
+        }
+        const bad = needId();
+        if (bad !== null)
+          return bad;
+        const sleep = io.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        const seen = new Map;
+        for (;; ) {
+          const running = (await io.client.runs(id)).filter((r) => r.status === "running");
+          for (const r of running) {
+            const phase = phaseOf(r);
+            if (seen.get(r.id) !== phase) {
+              seen.set(r.id, phase);
+              io.out(`${r.kind} ${r.id}: ${phase}`);
+            }
+          }
+          if (running.length === 0) {
+            io.out("Nothing running.");
+            return 0;
+          }
+          await sleep(POLL_MS);
+        }
+      }
+      case "reverify": {
+        const bad = needId();
+        if (bad !== null)
+          return bad;
+        if (!flags.includes("--yes")) {
+          io.out("This checks the plan's leads again: a stronger second pass on Opus, then a PoC for each bug it confirms. About 10 min, $3, charged only if it finishes.");
+          io.out(`Run again with --yes to start: sentinel reverify ${id} --yes`);
+          return 0;
+        }
+        const r = await io.client.reverify(id);
+        io.out(`${r.existing ? "Already running" : "Started"}: ${r.planId}`);
+        return 0;
+      }
+      case "login":
+      case "whoami": {
+        if (!io.auth)
+          return usage(`sentinel ${cmd} isn't available here`);
+        const withAuth = { ...io, auth: io.auth };
+        return cmd === "login" ? await login(flags, withAuth) : await whoami(io.client, withAuth);
+      }
+      case "logout":
+        return await logout(io);
+      case "new": {
+        if (!id)
+          return usage("sentinel new needs a contract id (SP….name) or a GitHub link");
+        const p = await io.client.previewPlan(id);
+        io.out(`${p.contractId}  ${p.kind === "prelaunch" ? "pre-launch code" : "deployed"}`);
+        if (p.planId)
+          io.out(`A plan already exists: ${p.planId}`);
+        const b = await io.client.billing();
+        io.out(b.prices ? `A new plan costs ${usd(b.prices.run)}, charged only if it finishes.` : "Billing isn't linked: the free daily plan limit applies.");
+        if (!flags.includes("--yes")) {
+          io.out(`Run again with --yes to start: sentinel new ${id} --yes`);
+          return 0;
+        }
+        const r = await io.client.createPlan(id);
+        io.out(`${r.cached ? "Already planned" : "Started"}: ${r.planId}`);
+        io.out(`Follow it with: sentinel runs ${r.planId}`);
+        return 0;
+      }
+      case "balance": {
+        const b = await io.client.billing();
+        if (json)
+          io.out(JSON.stringify(b, null, 2));
+        else if (b.unavailable)
+          io.out("Billing is unavailable right now. Try again.");
+        else if (!b.linked || b.balanceUsd === null || !b.prices)
+          io.out("Billing isn't linked. Open runsentinel.app to set it up.");
+        else {
+          io.out(`Balance: ${usd(b.balanceUsd)}`);
+          io.out(`Prices: plan ${usd(b.prices.run)}, deep run ${usd(b.prices.deepAudit)}, monitored event ${usd(b.prices.monitoredEvent)}`);
+        }
+        return 0;
+      }
+      case "alerts": {
+        const alerts = await io.client.alerts(values["--contract"]);
+        if (json)
+          io.out(JSON.stringify(alerts, null, 2));
+        else
+          for (const l of table([
+            ["ID", "WHEN", "LEVEL", "CONTRACT", "SUMMARY"],
+            ...alerts.map((a) => [a.id, a.createdAt, a.level, a.contractId, a.summary])
+          ]))
+            io.out(l);
+        return 0;
+      }
+      case "reproduce":
+      case "replay":
+      case "challenge":
+      case "directed":
+      case "tests":
+        return await ownerRun(cmd, args.slice(1), flags, io, usage);
+      case "watches":
+      case "rule":
+      case "mute":
+      case "unmute":
+      case "mute-alert":
+      case "destinations":
+      case "test-alert":
+      case "follow":
+      case "unfollow":
+        return await monitoring(cmd, args.slice(1), false, flags, values, io, usage);
+      default:
+        return usage(`Unknown command ${cmd}`);
+    }
+  } catch (e) {
+    io.err(e instanceof SentinelError || e instanceof SubjectError ? e.message : `Unexpected error: ${e.message}`);
+    return 1;
+  }
+}
+var usd = (n) => `$${n.toFixed(2)}`;
+var RUN_NOTE = "A paid run from your balance, charged only if it finishes.";
+async function ownerRun(cmd, pos, flags, io, usage) {
+  const [planId, second, third] = pos;
+  if (!planId)
+    return usage(`sentinel ${cmd} needs a plan id`);
+  let finding = 0;
+  if (cmd === "reproduce" || cmd === "replay" || cmd === "challenge") {
+    if (second === undefined || !/^\d+$/.test(second))
+      return usage(`sentinel ${cmd} needs a plan id and a finding number`);
+    finding = Number(second);
+  }
+  if (cmd === "challenge" && !third)
+    return usage("sentinel challenge needs a reason, in quotes");
+  if (cmd === "directed" && !second)
+    return usage("sentinel directed needs what to watch, in quotes");
+  if (cmd === "tests" && !flags.includes("--from-repo"))
+    return usage("sentinel tests needs --from-repo (a pre-launch plan's repo tests)");
+  const willDo = {
+    reproduce: `Write and run a PoC for finding ${finding} in the airgapped sandbox (never touches mainnet).`,
+    replay: `Re-run finding ${finding}'s stored PoC in the airgapped sandbox.`,
+    challenge: `Re-verify finding ${finding} against your argument.`,
+    directed: "Re-plan this contract around what you asked to have watched.",
+    tests: "Run the Clarinet suite from this pre-launch plan's repo in the airgapped sandbox."
+  }[cmd];
+  const flagTail = cmd === "tests" ? " --from-repo" : "";
+  const quoted = (v) => v ? ` ${JSON.stringify(v)}` : "";
+  const argTail = {
+    reproduce: ` ${finding}`,
+    replay: ` ${finding}`,
+    challenge: ` ${finding}${quoted(third)}`,
+    directed: quoted(second),
+    tests: ""
+  }[cmd];
+  if (!flags.includes("--yes")) {
+    io.out(willDo);
+    io.out(RUN_NOTE);
+    io.out(`Run again with --yes to start: sentinel ${cmd} ${planId}${argTail}${flagTail} --yes`);
+    return 0;
+  }
+  const r = await {
+    reproduce: () => io.client.reproduce(planId, finding),
+    replay: () => io.client.replay(planId, finding),
+    challenge: () => io.client.challenge(planId, finding, third),
+    directed: () => io.client.directed(planId, second),
+    tests: () => io.client.testsFromRepo(planId)
+  }[cmd]();
+  io.out(`${r.existing ? "Already running" : "Started"}: ${r.planId}`);
+  return 0;
+}
+var DURATIONS = { "1h": 1, "24h": 24, "7d": 168 };
+function previewOnly(io, flags, willDo, effect) {
+  if (flags.includes("--yes"))
+    return false;
+  if (willDo)
+    io.out(willDo);
+  io.out(`${effect} Run again with --yes to do it.`.trimStart());
+  return true;
+}
+async function monitoring(cmd, pos, on, flags, values, io, usage) {
+  const [first, second, third] = pos;
+  const need = (what) => usage(`sentinel ${cmd} needs ${what}`);
+  if (cmd === "mute-alert") {
+    if (!first)
+      return need("an alert id");
+    const dur = second ?? "24h";
+    if (!(dur in DURATIONS))
+      return usage("Mute for 1h, 24h or 7d");
+    const hours = DURATIONS[dur];
+    if (previewOnly(io, flags, `Mute the watch behind alert ${first} for ${dur}.`, "Takes effect now."))
+      return 0;
+    const r = await io.client.muteAlert(first, hours);
+    io.out(`Muted ${r.watchTitle} until ${r.mutedUntil}`);
+    return 0;
+  }
+  if (cmd === "follow" || cmd === "unfollow") {
+    if (!first)
+      return need("a contract id");
+    const follow = cmd === "follow";
+    const willDo = follow ? `Start monitoring ${first}.` : `Stop monitoring ${first}; your watches, alerts and settings for it are removed.`;
+    if (previewOnly(io, flags, willDo, follow ? "Nothing is on until you turn watches on." : ""))
+      return 0;
+    if (!follow) {
+      await io.client.stopMonitoring(await planOfContract(io.client, first));
+      io.out(`Stopped monitoring ${first}.`);
+      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.`);
+    return 0;
+  }
+  if (!first)
+    return need("a plan id");
+  const planId = first;
+  if (cmd === "test-alert") {
+    if (previewOnly(io, flags, "Send one sample alert to every place this plan's alerts go.", "Delivers now."))
+      return 0;
+    for (const r of (await io.client.testAlert(planId)).results) {
+      io.out(`${r.to}: ${r.ok ? "ok" : "failed"} ${r.detail}`.trimEnd());
+    }
+    return 0;
+  }
+  const ctx = await watchContext(io.client, planId);
+  if (cmd === "watches") {
+    if (flags.includes("--json")) {
+      io.out(JSON.stringify({ watches: ctx.watches }, 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)
+        io.out(`  ${w.status.padEnd(14)}${ruleSummary(w.rule, w.units)}`);
+    }
+    return 0;
+  }
+  if (cmd === "destinations") {
+    const next = await savedMonitor(io.client, planId);
+    const email = values["--email"];
+    if (email !== undefined && email !== "on" && email !== "off") {
+      return usage("--email takes on or off");
+    }
+    const asked = email !== undefined || "--webhook" in values || "--slack" in values;
+    const dest = {
+      emailAlerts: email === undefined ? next.emailAlerts : email === "on",
+      webhookUrl: values["--webhook"] ?? next.webhookUrl ?? "",
+      slackUrl: values["--slack"] ?? next.slackUrl ?? ""
+    };
+    const places = `${[dest.emailAlerts ? "email" : null, dest.webhookUrl ? "webhook" : null, dest.slackUrl ? "Slack" : null].filter(Boolean).join(", ") || "nowhere"}`;
+    if (!asked) {
+      io.out(`Alerts go to: ${places}`);
+      return 0;
+    }
+    if (previewOnly(io, flags, `Alerts would go to: ${places}.`, "Takes effect now."))
+      return 0;
+    const r = await io.client.monitorSettings(planId, {
+      watches: await savedChoices(io.client, planId) ?? undefined,
+      ...dest
+    });
+    io.out(`Alerts go to: ${places}`);
+    if (r.signingSecret)
+      io.out(`Webhook signing secret (shown once): ${r.signingSecret}`);
+    return 0;
+  }
+  if (!second)
+    return need("a subject (a function name or a token symbol)");
+  const g = resolveSubject(ctx.watches, second);
+  if (cmd === "rule") {
+    if (!third)
+      return need("a sentence describing the rule");
+    const parsed = await io.client.parseRule(planId, g.watches[0].subject, third);
+    for (const e of parsed.elsewhere)
+      io.out(`Belongs on another subject (${e.subjectKey}): ${e.phrase}`);
+    if (parsed.rules.length === 0) {
+      io.err(`Couldn't read a rule for ${g.name} from that.`);
+      return 1;
+    }
+    const plan = parsed.rules.map((rule) => ({
+      rule,
+      existing: g.watches.find((w) => w.rule.kind === rule.kind)
+    }));
+    for (const p of plan) {
+      io.out(`${p.existing ? "Set" : "Add"} on ${g.name}: ${ruleSummary(p.rule, g.watches[0].units)}`);
+    }
+    const effect = "Applied.";
+    if (previewOnly(io, flags, "", effect))
+      return 0;
+    for (const p of plan) {
+      if (p.existing)
+        await io.client.setRule(planId, p.existing.id, p.rule);
+      else
+        await io.client.addRule(planId, g.watches[0].subject, p.rule);
+    }
+    io.out(effect);
+    return 0;
+  }
+  if (cmd === "watch") {
+    const willDo = `Turn ${g.name} ${on ? "on" : "off"} (${g.watches.length} rule(s)).`;
+    const effect = on ? "Live now." : "Off now.";
+    if (previewOnly(io, flags, willDo, effect))
+      return 0;
+    const ids = g.watches.map((w) => w.id);
+    await io.client.setWatches(planId, ids, on);
+    io.out(`${willDo} ${effect}`);
+    return 0;
+  }
+  const mute = cmd === "mute";
+  const dur = third ?? "24h";
+  if (mute && !(dur in DURATIONS))
+    return usage("Mute for 1h, 24h or 7d");
+  const targets = g.watches.filter((w) => isMutableRule(w.rule));
+  if (targets.length === 0) {
+    io.err(`${g.name}'s watches come from a verified finding or governance review and can't be muted.`);
+    return 1;
+  }
+  const willDo = mute ? `Mute ${g.name} for ${dur}.` : `Unmute ${g.name}.`;
+  if (previewOnly(io, flags, willDo, "Takes effect now."))
+    return 0;
+  const mutedUntil = mute ? muteEnd(DURATIONS[dur]) : null;
+  for (const w of targets)
+    await io.client.mute(planId, w.id, mutedUntil);
+  io.out(mute ? `Muted ${g.name} until ${mutedUntil}` : `Unmuted ${g.name}.`);
+  return 0;
+}
+
+// cli/main.ts
+function takeToken(argv) {
+  const i = argv.indexOf("--token");
+  if (i === -1)
+    return { argv };
+  return { argv: argv.filter((_, j) => j !== i && j !== i + 1), token: argv[i + 1] };
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin)
+    chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+async function main() {
+  const { argv, token: flag } = takeToken(process.argv.slice(2));
+  const cmd = argv.find((a) => !a.startsWith("--"));
+  const help = argv.length === 0 || cmd === "help" || argv.includes("--help");
+  const credential = await resolveToken(flag);
+  if (!credential && !help && cmd !== "login" && cmd !== "logout") {
+    console.error(NOT_LOGGED_IN);
+    return 2;
+  }
+  const baseUrl = process.env.SENTINEL_API_URL;
+  const clientFor = (token) => createClient({ token, baseUrl });
+  return run(argv, {
+    client: clientFor(credential?.token ?? ""),
+    out: console.log,
+    err: console.error,
+    auth: { source: credential?.source ?? null, clientFor, prompt, readStdin }
+  });
+}
+process.exit(await main());