@matteai/stma 0.2.1 → 0.11.1

package/dist/index.js

@@ -7,10 +7,10 @@ var __export = (target, all2) => {
 
 // src/index.ts
 import { createHash as createHash3, randomUUID } from "crypto";
-import { execFileSync, spawn } from "child_process";
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, readdirSync, writeFileSync as writeFileSync3 } from "fs";
-import os from "os";
-import path3 from "path";
+import { execFileSync as execFileSync2, spawn as spawn2 } from "child_process";
+import { existsSync as existsSync5, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import os2 from "os";
+import path5 from "path";
 
 // src/adapters.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -102,15 +102,387 @@ function loadAdapterConfig(root) {
   return JSON.parse(readFileSync(file, "utf8"));
 }
 
+// src/collect.ts
+import { execFileSync } from "child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync } from "fs";
+import path2 from "path";
+var firstVersion = (raw) => /(\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?)/.exec(raw)?.[1];
+var bare = (raw) => firstVersion(raw) ?? raw.split(/\r?\n/)[0]?.trim();
+var RUNTIME_PROBES = [
+  {
+    when: ["*"],
+    probes: [{ key: "git", command: "git", args: ["--version"], parse: firstVersion }]
+  },
+  {
+    when: ["requirements.txt", "pyproject.toml", "Pipfile", "setup.py", "setup.cfg", ".python-version", "tox.ini"],
+    probes: [
+      { key: "python", command: "python3", args: ["--version"], parse: firstVersion },
+      { key: "python", command: "python", args: ["--version"], parse: firstVersion }
+    ]
+  },
+  { when: ["go.mod", "go.work"], probes: [{ key: "go", command: "go", args: ["version"], parse: firstVersion }] },
+  {
+    when: ["Cargo.toml"],
+    probes: [{ key: "rust", command: "rustc", args: ["--version"], parse: firstVersion }]
+  },
+  {
+    when: ["pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle"],
+    probes: [{ key: "java", command: "java", args: ["-version"], parse: firstVersion }]
+  },
+  {
+    when: ["Gemfile", ".ruby-version", "Rakefile"],
+    probes: [{ key: "ruby", command: "ruby", args: ["--version"], parse: firstVersion }]
+  },
+  {
+    when: ["composer.json"],
+    probes: [{ key: "php", command: "php", args: ["--version"], parse: firstVersion }]
+  },
+  {
+    when: ["global.json", "*.csproj", "*.fsproj", "*.sln"],
+    probes: [{ key: "dotnet", command: "dotnet", args: ["--version"], parse: bare }]
+  },
+  {
+    when: ["mix.exs"],
+    probes: [{ key: "elixir", command: "elixir", args: ["--version"], parse: firstVersion }]
+  },
+  {
+    when: ["pubspec.yaml"],
+    probes: [{ key: "dart", command: "dart", args: ["--version"], parse: firstVersion }]
+  },
+  {
+    // Containers are where "works on my machine" hides once the languages match.
+    when: ["Dockerfile", "docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"],
+    probes: [{ key: "docker", command: "docker", args: ["--version"], parse: firstVersion }]
+  }
+];
+var PM_PROBES = [
+  { when: ["pnpm-lock.yaml"], probes: [{ key: "pnpm", command: "pnpm", args: ["--version"], parse: bare }] },
+  { when: ["yarn.lock"], probes: [{ key: "yarn", command: "yarn", args: ["--version"], parse: bare }] },
+  { when: ["bun.lockb", "bun.lock"], probes: [{ key: "bun", command: "bun", args: ["--version"], parse: bare }] },
+  {
+    when: ["requirements.txt", "pyproject.toml", "Pipfile", "setup.py"],
+    probes: [
+      { key: "pip", command: "pip3", args: ["--version"], parse: firstVersion },
+      { key: "pip", command: "pip", args: ["--version"], parse: firstVersion }
+    ]
+  },
+  { when: ["poetry.lock"], probes: [{ key: "poetry", command: "poetry", args: ["--version"], parse: firstVersion }] },
+  { when: ["uv.lock"], probes: [{ key: "uv", command: "uv", args: ["--version"], parse: firstVersion }] },
+  { when: ["Gemfile"], probes: [{ key: "bundler", command: "bundle", args: ["--version"], parse: firstVersion }] },
+  { when: ["composer.json"], probes: [{ key: "composer", command: "composer", args: ["--version"], parse: firstVersion }] },
+  { when: ["Cargo.toml"], probes: [{ key: "cargo", command: "cargo", args: ["--version"], parse: firstVersion }] },
+  { when: ["pom.xml"], probes: [{ key: "maven", command: "mvn", args: ["--version"], parse: firstVersion }] },
+  {
+    when: ["build.gradle", "build.gradle.kts", "gradlew"],
+    probes: [{ key: "gradle", command: "gradle", args: ["--version"], parse: firstVersion }]
+  },
+  { when: ["mix.exs"], probes: [{ key: "mix", command: "mix", args: ["--version"], parse: firstVersion }] }
+];
+var LOCKFILE_NAMES = [
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "npm-shrinkwrap.json",
+  "bun.lockb",
+  "bun.lock",
+  "poetry.lock",
+  "uv.lock",
+  "Pipfile.lock",
+  "pdm.lock",
+  "requirements.txt",
+  "go.sum",
+  "Cargo.lock",
+  "Gemfile.lock",
+  "composer.lock",
+  "packages.lock.json",
+  "gradle.lockfile",
+  "mix.lock",
+  "pubspec.lock",
+  "flake.lock"
+];
+function hasMarker(dir, markers, entries) {
+  if (markers.includes("*")) return true;
+  const plain = markers.filter((m) => !m.startsWith("*."));
+  if (plain.some((m) => existsSync2(path2.join(dir, m)))) return true;
+  const globs = markers.filter((m) => m.startsWith("*.")).map((m) => m.slice(1));
+  if (globs.length === 0) return false;
+  const names = entries ?? safeList(dir);
+  return names.some((name) => globs.some((ext) => name.endsWith(ext)));
+}
+function safeList(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+function run(dir, probe) {
+  try {
+    const raw = execFileSync(probe.command, probe.args, {
+      cwd: dir,
+      encoding: "utf8",
+      // `java -version` prints to stderr; merging means one code path for both.
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: 4e3
+    });
+    const text = String(raw).trim();
+    return (probe.parse ? probe.parse(text) : text) || void 0;
+  } catch (error) {
+    const stderr = error.stderr;
+    if (stderr) {
+      const text = String(stderr).trim();
+      const parsed = probe.parse ? probe.parse(text) : text;
+      if (parsed) return parsed;
+    }
+    return void 0;
+  }
+}
+function collectGroup(dir, groups, entries) {
+  const out = {};
+  for (const group of groups) {
+    if (!hasMarker(dir, group.when, entries)) continue;
+    for (const probe of group.probes) {
+      if (out[probe.key]) continue;
+      const value = run(dir, probe);
+      if (value) out[probe.key] = value;
+    }
+  }
+  return out;
+}
+var ECOSYSTEM_NAMES = [
+  ["node", ["package.json"]],
+  ["python", ["requirements.txt", "pyproject.toml", "Pipfile", "setup.py"]],
+  ["go", ["go.mod", "go.work"]],
+  ["rust", ["Cargo.toml"]],
+  ["java", ["pom.xml", "build.gradle", "build.gradle.kts"]],
+  ["ruby", ["Gemfile"]],
+  ["php", ["composer.json"]],
+  ["dotnet", ["global.json", "*.csproj", "*.fsproj", "*.sln"]],
+  ["elixir", ["mix.exs"]],
+  ["dart", ["pubspec.yaml"]],
+  ["docker", ["Dockerfile", "docker-compose.yml", "compose.yaml"]]
+];
+function scanEcosystems(dir) {
+  const entries = safeList(dir);
+  return {
+    runtimes: collectGroup(dir, RUNTIME_PROBES, entries),
+    packageManagers: collectGroup(dir, PM_PROBES, entries),
+    ecosystems: ECOSYSTEM_NAMES.filter(([, markers]) => hasMarker(dir, markers, entries)).map(
+      ([name]) => name
+    )
+  };
+}
+var DOTENV_TEMPLATE = /(^|\.)(example|sample|template|dist|defaults?)$/i;
+function dotenvNames(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const names = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!/^\.env(?:\..+)?$/.test(entry.name)) continue;
+    if (DOTENV_TEMPLATE.test(entry.name)) continue;
+    let body;
+    try {
+      body = readFileSync2(path2.join(dir, entry.name), "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of body.split(/\r?\n/)) {
+      const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+      if (match) names.push(match[1]);
+    }
+  }
+  return names;
+}
+
+// src/news.ts
+var NEWS_MIN_INTERVAL_MS = 6e4;
+var NEWS_TIMEOUT_MS = 2500;
+function dueForCheck(state, now = Date.now()) {
+  if (!state.lastCheckedAt) return true;
+  const last = Date.parse(state.lastCheckedAt);
+  return !Number.isFinite(last) || now - last >= NEWS_MIN_INTERVAL_MS;
+}
+var handoffKey = (handoff) => `${handoff.sessionId}:${handoff.at}`;
+function unseen(news, state) {
+  const seen = new Set(state.announced ?? []);
+  return news.pendingHandoffs.filter((h) => !seen.has(handoffKey(h)));
+}
+function rememberAnnounced(state, handoffs) {
+  return [.../* @__PURE__ */ new Set([...state.announced ?? [], ...handoffs.map(handoffKey)])].slice(-50);
+}
+function renderNews(handoffs, unreadSessions) {
+  if (handoffs.length === 0 && unreadSessions === 0) return void 0;
+  const lines = [];
+  for (const handoff of handoffs.slice(0, 3)) {
+    const who = handoff.mine ? "your own agent on another machine" : handoff.from ?? "a teammate";
+    const where = handoff.resume?.branch ? ` on \`${handoff.resume.branch}\`` : "";
+    lines.push(`STMA \u2014 work is waiting: "${handoff.title}"${where}, handed over by ${who}.`);
+    const steps = handoff.resume?.steps ?? [];
+    if (steps.length > 0) lines.push(`  Next: ${steps.slice(0, 2).join("; ")}`);
+    if (handoff.resume?.checkout) lines.push(`  Take it: ${handoff.resume.checkout}`);
+    if (handoff.resume?.reclaim) {
+      lines.push(
+        `  Then re-claim the same scope: ${handoff.resume.reclaim.tool} ${JSON.stringify(
+          handoff.resume.reclaim.arguments
+        )}`
+      );
+    }
+    lines.push(`  Read it in full with get_session {"session_id":"${handoff.sessionId}"}.`);
+  }
+  if (unreadSessions > 0) {
+    lines.push(
+      `STMA \u2014 ${unreadSessions} debug ${unreadSessions === 1 ? "session has" : "sessions have"} unread replies. Call inbox to read them.`
+    );
+  }
+  lines.push(
+    "Tell your human what is waiting and ask before acting on it \u2014 do not check out a branch or start a run unprompted."
+  );
+  return lines.join("\n");
+}
+
 // src/hash.ts
 import { createHash } from "crypto";
 function gitBlobHash(content) {
   return createHash("sha1").update(`blob ${content.byteLength}\0`).update(content).digest("hex");
 }
 
+// src/serve.ts
+import { spawn } from "child_process";
+import { createRequire } from "module";
+import { existsSync as existsSync3 } from "fs";
+import os from "os";
+import path3 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+
+// src/version.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { fileURLToPath } from "url";
+function readVersion() {
+  try {
+    const manifest = fileURLToPath(new URL("../package.json", import.meta.url));
+    return JSON.parse(readFileSync3(manifest, "utf8")).version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+var VERSION = readVersion();
+var CLIENT_HEADER = "x-stma-client";
+var clientHeaders = () => ({ [CLIENT_HEADER]: `stma/${VERSION}` });
+
+// src/serve.ts
+var SERVER_PACKAGE = "@matteai/stma-server";
+function serverSpec(version2 = VERSION) {
+  return /^\d+\.\d+\.\d+$/.test(version2) ? `${SERVER_PACKAGE}@${version2}` : SERVER_PACKAGE;
+}
+var defaultDataDir = () => path3.join(os.homedir(), ".stma", "data");
+function resolveServerEntry() {
+  const require2 = createRequire(import.meta.url);
+  try {
+    const manifest = require2.resolve(`${SERVER_PACKAGE}/package.json`);
+    const entry = path3.join(path3.dirname(manifest), "dist", "index.js");
+    if (existsSync3(entry)) return entry;
+  } catch {
+  }
+  const here = path3.dirname(fileURLToPath2(import.meta.url));
+  for (const candidate of [
+    path3.resolve(here, "../../server/dist/index.js"),
+    path3.resolve(here, "../../../server/dist/index.js")
+  ]) {
+    if (existsSync3(candidate)) return candidate;
+  }
+  return null;
+}
+function serveEnv(options) {
+  const base = `http://${options.host === "0.0.0.0" ? "localhost" : options.host}:${options.port}`;
+  return {
+    ...process.env,
+    NODE_ENV: "production",
+    HOST: options.host,
+    PORT: String(options.port),
+    BASE_URL: base,
+    EMBEDDED_DB: "1",
+    PGLITE_DIR: options.dataDir,
+    // Local accounts with open signup: the person who runs this is the person
+    // who should get the first account. Dev auth is deliberately NOT enabled —
+    // a passwordless login form is not a thing to hand somebody by default,
+    // even on localhost.
+    AUTH_LOCAL: "1",
+    SIGNUPS_OPEN: "1",
+    AUTH_2FA: "0"
+  };
+}
+function connectSnippet(base) {
+  return `claude mcp add --scope user --transport http stma ${base}/mcp --header "Authorization: Bearer stma_YOUR_TOKEN"`;
+}
+async function waitForHealth(base, child) {
+  const deadline = Date.now() + 9e4;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) return false;
+    try {
+      const res = await fetch(`${base}/health`);
+      if (res.ok) return true;
+    } catch {
+    }
+    await new Promise((resolve) => setTimeout(resolve, 400));
+  }
+  return false;
+}
+async function serve(options) {
+  const base = `http://${options.host === "0.0.0.0" ? "localhost" : options.host}:${options.port}`;
+  const entry = resolveServerEntry();
+  const env = serveEnv(options);
+  const child = entry ? spawn(process.execPath, [entry], { env, stdio: ["ignore", "inherit", "inherit"] }) : (
+    // No local copy: fetch it once, exactly as npx would. Said out loud, because
+    // a command that silently downloads a server is not a command anyone should trust.
+    (console.log(`Fetching ${serverSpec()} (first run only)\u2026`), spawn("npx", ["-y", serverSpec()], {
+      env,
+      stdio: ["ignore", "inherit", "inherit"],
+      shell: process.platform === "win32"
+    }))
+  );
+  const stop = () => {
+    child.kill("SIGINT");
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  child.on("exit", (code) => process.exit(code ?? 0));
+  const healthy = await waitForHealth(base, child);
+  if (!healthy) {
+    console.error(
+      child.exitCode !== null ? `
+The server exited before it was ready.${entry ? "" : `
+If ${SERVER_PACKAGE} could not be fetched, install it once: npm i -g ${SERVER_PACKAGE}`}` : `
+The server did not answer ${base}/health in 90s. Something else may be on port ${options.port} \u2014 try --port.`
+    );
+    return;
+  }
+  console.log(
+    [
+      "",
+      `  STMA is running at ${base}`,
+      "",
+      `  1. Create your account   ${base}/signup`,
+      `  2. Create a token        ${base}/app/tokens`,
+      "  3. Connect your agent:",
+      "",
+      `     ${connectSnippet(base)}`,
+      "",
+      `  Guide  ${base}/docs`,
+      `  Data   ${options.dataDir}`,
+      "  Stop   Ctrl+C",
+      ""
+    ].join("\n")
+  );
+}
+
 // src/policy.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import path2 from "path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import path4 from "path";
 
 // ../../node_modules/zod/v3/external.js
 var external_exports = {};
@@ -590,8 +962,8 @@ function getErrorMap() {
 
 // ../../node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path4, errorMaps, issueData } = params;
-  const fullPath = [...path4, ...issueData.path || []];
+  const { data, path: path6, errorMaps, issueData } = params;
+  const fullPath = [...path6, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -707,11 +1079,11 @@ var errorUtil;
 
 // ../../node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path4, key) {
+  constructor(parent, value, path6, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path4;
+    this._path = path6;
     this._key = key;
   }
   get path() {
@@ -1090,11 +1462,11 @@ function datetimeRegex(args) {
   regex = `${regex}(${opts.join("|")})`;
   return new RegExp(`^${regex}$`);
 }
-function isValidIP(ip, version) {
-  if ((version === "v4" || !version) && ipv4Regex.test(ip)) {
+function isValidIP(ip, version2) {
+  if ((version2 === "v4" || !version2) && ipv4Regex.test(ip)) {
     return true;
   }
-  if ((version === "v6" || !version) && ipv6Regex.test(ip)) {
+  if ((version2 === "v6" || !version2) && ipv6Regex.test(ip)) {
     return true;
   }
   return false;
@@ -1121,11 +1493,11 @@ function isValidJWT(jwt, alg) {
     return false;
   }
 }
-function isValidCidr(ip, version) {
-  if ((version === "v4" || !version) && ipv4CidrRegex.test(ip)) {
+function isValidCidr(ip, version2) {
+  if ((version2 === "v4" || !version2) && ipv4CidrRegex.test(ip)) {
     return true;
   }
-  if ((version === "v6" || !version) && ipv6CidrRegex.test(ip)) {
+  if ((version2 === "v6" || !version2) && ipv6CidrRegex.test(ip)) {
     return true;
   }
   return false;
@@ -4154,7 +4526,7 @@ var coerce = {
 var NEVER = INVALID;
 
 // ../shared/src/snapshot.ts
-var snapshotSchema = external_exports.object({
+var snapshotSchema = external_exports.strictObject({
   schemaVersion: external_exports.literal(1).default(1),
   os: external_exports.object({
     platform: external_exports.string().max(40),
@@ -4166,9 +4538,16 @@ var snapshotSchema = external_exports.object({
   runtimes: external_exports.record(external_exports.string().max(200)).default({}),
   /** e.g. { npm: "11.6.2", pnpm: "9.0.0" } */
   packageManagers: external_exports.record(external_exports.string().max(200)).default({}),
-  lockfiles: external_exports.array(external_exports.object({ path: external_exports.string().max(300), hash: external_exports.string().max(128) })).max(50).default([]),
-  /** Names only, never values. */
-  envVarNames: external_exports.array(external_exports.string().max(200)).max(1e3).default([]),
+  lockfiles: external_exports.array(external_exports.object({ path: external_exports.string().max(300), hash: external_exports.string().max(128) })).max(50).default([]).refine((files) => new Set(files.map((f) => f.path)).size === files.length, {
+    message: "lockfiles must not list the same path twice"
+  }),
+  /**
+   * Names only, never values. Optional rather than defaulted to `[]`: an absent
+   * list means "this machine was not asked", and a preflight that cannot tell
+   * that from "this machine has nothing" reports every required variable as
+   * missing on a snapshot nobody actually inspected.
+   */
+  envVarNames: external_exports.array(external_exports.string().max(200)).max(1e3).optional(),
   git: external_exports.object({
     branch: external_exports.string().max(300).optional(),
     sha: external_exports.string().max(64).optional(),
@@ -4214,12 +4593,36 @@ var workClaimSchema = external_exports.object({
   resourceKey: external_exports.string().trim().min(1).max(500),
   access: claimAccessModeSchema.default("write")
 });
+var QUOTA_STATES = ["ok", "warning", "critical"];
+var quotaStateSchema = external_exports.enum(QUOTA_STATES);
+var QUOTA_SOURCES = ["measured", "estimate"];
+var quotaSourceSchema = external_exports.enum(QUOTA_SOURCES);
+var agentQuotaSchema = external_exports.object({
+  /** How much of the current window is spent, 0-100. */
+  usedPct: external_exports.number().min(0).max(100),
+  /** When the vendor window resets, if the client knows. */
+  resetsAt: external_exports.string().datetime().optional(),
+  /** What the allowance is called on the client, e.g. "claude 5h window". */
+  label: external_exports.string().trim().max(80).optional(),
+  /** Read from something real, or guessed. Absent means guessed. */
+  source: quotaSourceSchema.default("estimate")
+});
+var AGENT_ROLES = [
+  "generalist",
+  "implementer",
+  "reviewer",
+  "tester",
+  "planner",
+  "ops"
+];
+var agentRoleSchema = external_exports.enum(AGENT_ROLES);
 var registerAgentSchema = external_exports.object({
   name: external_exports.string().trim().min(1).max(80),
   clientType: agentClientTypeSchema.default("generic"),
   clientVersion: external_exports.string().trim().max(80).optional(),
   deviceFingerprint: external_exports.string().trim().min(8).max(128),
-  capabilities: external_exports.array(external_exports.string().trim().min(1).max(80)).max(50).default([])
+  capabilities: external_exports.array(external_exports.string().trim().min(1).max(80)).max(50).default([]),
+  role: agentRoleSchema.optional()
 });
 var startAgentRunSchema = external_exports.object({
   installationId: external_exports.string().uuid(),
@@ -4231,11 +4634,19 @@ var startAgentRunSchema = external_exports.object({
   branch: external_exports.string().trim().max(300).optional(),
   worktree: external_exports.string().trim().max(500).optional(),
   baseSha: external_exports.string().trim().max(64).optional(),
-  claims: external_exports.array(workClaimSchema).max(200).default([])
+  claims: external_exports.array(workClaimSchema).max(200).default([]),
+  /**
+   * Runs that are deliberately parallel attempts at the same task. Agents in one
+   * group never warn each other: fanning one prompt across three worktrees is the
+   * normal way to work now, and reporting it as three collisions made the radar
+   * useless exactly where it was busiest.
+   */
+  attemptGroup: external_exports.string().trim().min(1).max(120).optional()
 });
 var heartbeatAgentRunSchema = external_exports.object({
   status: external_exports.enum(["active", "waiting", "blocked"]).optional(),
-  claims: external_exports.array(workClaimSchema).max(200).optional()
+  claims: external_exports.array(workClaimSchema).max(200).optional(),
+  usage: agentQuotaSchema.optional()
 });
 var finishAgentRunSchema = external_exports.object({
   status: external_exports.enum(["completed", "failed"]).default("completed"),
@@ -4254,7 +4665,39 @@ var policyDocumentSchema = external_exports.object({
   environment: external_exports.object({
     requiredEnvVarNames: external_exports.array(external_exports.string().trim().min(1).max(200)).max(500).default([]),
     runtimes: external_exports.record(external_exports.string().trim().max(200)).default({})
-  }).default({ requiredEnvVarNames: [], runtimes: {} })
+  }).default({ requiredEnvVarNames: [], runtimes: {} }),
+  /**
+   * How much a run may do on this ground before a person is in the loop.
+   *
+   * "Allow the agent or don't" is too coarse to be useful: the same agent that
+   * should freely edit a test file should not quietly rewrite a migration
+   * chain. The tier belongs to the *work*, not to the agent — so it is declared
+   * per claim type, which is the only thing a run states before it starts.
+   *
+   * This tells; it does not block. Claims are advisory here by design, and a
+   * gate an agent can route around is worse than a sentence it can read.
+   */
+  autonomy: external_exports.object({
+    /** Claim types a run must get a human to agree to before changing. */
+    requireApprovalFor: external_exports.array(external_exports.enum(CLAIM_RESOURCE_TYPES)).max(8).default([])
+  }).default({ requireApprovalFor: [] }),
+  /**
+   * Small batches, as a rule rather than as advice.
+   *
+   * DORA's clearest countermeasure to AI-sized changes is keeping them small,
+   * and the cheapest moment to say so is before the work starts — the run has
+   * already declared its scope by then, so the number is knowable and the
+   * suggestion ("split it") is still free to act on.
+   *
+   * 0 means no budget, which is the default: a limit nobody chose should not
+   * start warning people.
+   */
+  changeBudget: external_exports.object({
+    /** Total claims one run may declare. */
+    maxScopeItems: external_exports.number().int().min(0).max(200).default(0),
+    /** Path claims specifically — the ones that turn into review minutes. */
+    maxPaths: external_exports.number().int().min(0).max(200).default(0)
+  }).default({ maxScopeItems: 0, maxPaths: 0 })
 });
 
 // ../shared/src/fingerprint.ts
@@ -4271,6 +4714,48 @@ function sortValue(value) {
 var canonicalJson = (value) => JSON.stringify(sortValue(value));
 var fingerprintJson = (value) => createHash2("sha256").update(canonicalJson(value)).digest("hex");
 
+// ../shared/src/delivery.ts
+var TICKET_SYSTEMS = ["jira", "github", "azure-boards", "none"];
+var DEPLOY_TRIGGERS = ["merge", "tag", "manual"];
+var MERGE_STRATEGIES = ["merge", "squash", "rebase"];
+var flowEnvironmentSchema = external_exports.object({
+  /** "stage", "uat", "prod" — also the CI environment name. */
+  name: external_exports.string().trim().min(1).max(40).regex(/^[a-zA-Z0-9._-]+$/, "letters, digits, dots, dashes"),
+  /** What sends a build here: every merge, a version tag, or a person. */
+  deployOn: external_exports.enum(DEPLOY_TRIGGERS).default("manual"),
+  /** Somebody signs off before the deploy runs (approval gate on the CI environment). */
+  approval: external_exports.boolean().default(false)
+});
+var deliveryFlowSchema = external_exports.object({
+  /** One sentence a newcomer reads first. */
+  intro: external_exports.string().trim().max(300).default(""),
+  ticket: external_exports.object({
+    system: external_exports.enum(TICKET_SYSTEMS).default("none"),
+    /** Example key, e.g. "PROJ-123" — the shape, not a real ticket. */
+    keyPattern: external_exports.string().trim().max(60).default(""),
+    /** Work must not start without a ticket. */
+    required: external_exports.boolean().default(false)
+  }).default({}),
+  branch: external_exports.object({
+    /** Naming rule with placeholders: {ticket}, {slug}, {type}. */
+    pattern: external_exports.string().trim().min(1).max(120).default("feature/{ticket}-{slug}"),
+    /** The branch work forks from and merges back to. */
+    from: external_exports.string().trim().min(1).max(60).default("main")
+  }).default({}),
+  /** Commands that must pass before a PR is opened; also the CI check stage. */
+  checks: external_exports.array(external_exports.string().trim().min(1).max(200)).max(20).default([]),
+  review: external_exports.object({
+    /** Approvals a PR needs before merge. 0 means none required. */
+    approvals: external_exports.number().int().min(0).max(10).default(1)
+  }).default({}),
+  mergeStrategy: external_exports.enum(MERGE_STRATEGIES).default("squash"),
+  /** The road to production, in order. Empty means CI-only, no deploys. */
+  environments: external_exports.array(flowEnvironmentSchema).max(8).default([]),
+  /** Extra house rules that fit no field above. */
+  notes: external_exports.array(external_exports.string().trim().min(1).max(300)).max(20).default([])
+});
+var EMPTY_DELIVERY_FLOW = deliveryFlowSchema.parse({});
+
 // src/policy.ts
 function managedPolicyBlock(document, hash) {
   const lines = [
@@ -4302,7 +4787,7 @@ function managedPolicyBlock(document, hash) {
   const environment2 = [
     ...document.environment.requiredEnvVarNames.map((name) => `- Required env var: ${name}`),
     ...Object.entries(document.environment.runtimes).map(
-      ([runtime, version]) => `- Expected ${runtime} version: ${version}`
+      ([runtime, version2]) => `- Expected ${runtime} version: ${version2}`
     )
   ];
   if (environment2.length) {
@@ -4313,8 +4798,8 @@ function managedPolicyBlock(document, hash) {
 `;
 }
 function writeManagedPolicy(file, block, prefix = "") {
-  mkdirSync2(path2.dirname(file), { recursive: true });
-  const existing = existsSync2(file) ? readFileSync2(file, "utf8") : prefix;
+  mkdirSync2(path4.dirname(file), { recursive: true });
+  const existing = existsSync4(file) ? readFileSync4(file, "utf8") : prefix;
   const marker = /<!-- STMA:BEGIN managed policy -->[\s\S]*?<!-- STMA:END managed policy -->\s*/;
   const next = marker.test(existing) ? existing.replace(marker, block) : `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block}`;
   writeFileSync2(file, next, "utf8");
@@ -4322,7 +4807,7 @@ function writeManagedPolicy(file, block, prefix = "") {
 function appliedPolicyHash(root) {
   try {
     const persisted = JSON.parse(
-      readFileSync2(path2.join(root, ".stma", "effective-policy.json"), "utf8")
+      readFileSync4(path4.join(root, ".stma", "effective-policy.json"), "utf8")
     );
     return persisted.document === void 0 ? void 0 : fingerprintJson(persisted.document);
   } catch {
@@ -4330,35 +4815,35 @@ function appliedPolicyHash(root) {
   }
 }
 function applyPolicy(root, document, hash, clientType) {
-  const stmaDir2 = path2.join(root, ".stma");
+  const stmaDir2 = path4.join(root, ".stma");
   mkdirSync2(stmaDir2, { recursive: true });
   writeFileSync2(
-    path2.join(stmaDir2, "effective-policy.json"),
+    path4.join(stmaDir2, "effective-policy.json"),
     `${JSON.stringify({ hash, document }, null, 2)}
 `,
     "utf8"
   );
   const block = managedPolicyBlock(document, hash);
   if (clientType === "claude-code") {
-    writeManagedPolicy(path2.join(root, "CLAUDE.md"), block);
+    writeManagedPolicy(path4.join(root, "CLAUDE.md"), block);
   } else if (clientType === "cursor") {
     const frontmatter = "---\ndescription: STMA organization and project policy\nalwaysApply: true\n---\n\n";
-    writeManagedPolicy(path2.join(root, ".cursor", "rules", "stma-policy.mdc"), block, frontmatter);
+    writeManagedPolicy(path4.join(root, ".cursor", "rules", "stma-policy.mdc"), block, frontmatter);
   } else {
-    writeManagedPolicy(path2.join(root, "AGENTS.md"), block);
+    writeManagedPolicy(path4.join(root, "AGENTS.md"), block);
   }
   return appliedPolicyHash(root);
 }
 
 // src/index.ts
 var cwd = process.cwd();
-var stmaDir = path3.join(cwd, ".stma");
-var configPath = path3.join(stmaDir, "local.json");
-var outboxPath = path3.join(stmaDir, "outbox.json");
+var stmaDir = path5.join(cwd, ".stma");
+var configPath = path5.join(stmaDir, "local.json");
+var outboxPath = path5.join(stmaDir, "outbox.json");
 function loadConfig() {
-  if (!existsSync3(configPath)) return {};
+  if (!existsSync5(configPath)) return {};
   try {
-    return JSON.parse(readFileSync3(configPath, "utf8"));
+    return JSON.parse(readFileSync5(configPath, "utf8"));
   } catch {
     fail(`Could not read ${configPath}. Fix or remove the invalid JSON file.`);
   }
@@ -4396,14 +4881,14 @@ function fail(message) {
 }
 function shell(command, args) {
   try {
-    return execFileSync(command, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    return execFileSync2(command, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   } catch {
     return void 0;
   }
 }
 function gitContext() {
   return {
-    repo: path3.basename(shell("git", ["rev-parse", "--show-toplevel"]) ?? cwd),
+    repo: path5.basename(shell("git", ["rev-parse", "--show-toplevel"]) ?? cwd),
     branch: shell("git", ["branch", "--show-current"]),
     baseSha: shell("git", ["rev-parse", "HEAD"]),
     worktree: shell("git", ["rev-parse", "--show-toplevel"])
@@ -4428,38 +4913,21 @@ function parseClaim(value) {
 function sha256(data) {
   return createHash3("sha256").update(data).digest("hex");
 }
-function dotenvNames() {
-  const candidates = readdirSync(cwd, { withFileTypes: true }).filter((entry) => entry.isFile() && /^\.env(?:\..+)?$/.test(entry.name)).map((entry) => entry.name);
-  const names = [];
-  for (const file of candidates) {
-    for (const line of readFileSync3(path3.join(cwd, file), "utf8").split(/\r?\n/)) {
-      const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
-      if (match) names.push(match[1]);
-    }
-  }
-  return names;
-}
 function collectSnapshot() {
-  const lockfileNames = [
-    "package-lock.json",
-    "pnpm-lock.yaml",
-    "yarn.lock",
-    "poetry.lock",
-    "uv.lock",
-    "go.sum",
-    "Cargo.lock"
-  ];
-  const lockfiles = lockfileNames.filter((name) => existsSync3(path3.join(cwd, name))).map((name) => ({ path: name, hash: gitBlobHash(readFileSync3(path3.join(cwd, name))) }));
+  const lockfiles = LOCKFILE_NAMES.filter((name) => existsSync5(path5.join(cwd, name))).map(
+    (name) => ({ path: name, hash: gitBlobHash(readFileSync5(path5.join(cwd, name))) })
+  );
   const git = gitContext();
-  const npmVersion = shell("npm", ["--version"]);
+  const npmVersion = existsSync5(path5.join(cwd, "package.json")) ? shell("npm", ["--version"]) : void 0;
+  const scan = scanEcosystems(cwd);
   return {
     schemaVersion: 1,
-    os: { platform: process.platform, release: os.release(), arch: process.arch },
+    os: { platform: process.platform, release: os2.release(), arch: process.arch },
     shell: process.env.SHELL ?? process.env.ComSpec,
-    runtimes: { node: process.version.replace(/^v/, "") },
-    packageManagers: { ...npmVersion ? { npm: npmVersion } : {} },
+    runtimes: { node: process.version.replace(/^v/, ""), ...scan.runtimes },
+    packageManagers: { ...npmVersion ? { npm: npmVersion } : {}, ...scan.packageManagers },
     lockfiles,
-    envVarNames: [.../* @__PURE__ */ new Set([...Object.keys(process.env), ...dotenvNames()])].sort(),
+    envVarNames: [.../* @__PURE__ */ new Set([...Object.keys(process.env), ...dotenvNames(cwd)])].sort(),
     git: {
       branch: git.branch,
       sha: git.baseSha,
@@ -4484,19 +4952,41 @@ async function apiRequest(config, endpoint, init = {}) {
     headers: {
       authorization: `Bearer ${token}`,
       "content-type": "application/json",
+      // Say which client this is on every call. The server never requires it —
+      // an older CLI has to keep working — but a version mix that is visible in
+      // the logs is one nobody has to reconstruct from a bug report.
+      ...clientHeaders(),
       ...init.headers
     }
   });
   const data = await response.json().catch(() => ({}));
-  if (!response.ok) throw new Error(data.error ?? `HTTP ${response.status}`);
+  if (!response.ok) {
+    const failure = Object.assign(new Error(data.error ?? `HTTP ${response.status}`), {
+      status: response.status
+    });
+    throw failure;
+  }
   return data;
 }
+async function skewNote(server) {
+  try {
+    const res = await fetch(`${server}/health`, { signal: AbortSignal.timeout(2e3) });
+    const health = await res.json();
+    if (!health.version || health.version === VERSION) return "";
+    return `
+  The server reports version ${health.version}; this CLI is ${VERSION}. If that endpoint is newer than the server, upgrade it (npm i -g @matteai/stma-server) or use a CLI of the same version.`;
+  } catch {
+    return "";
+  }
+}
 async function request(config, endpoint, init = {}) {
   try {
     return await apiRequest(config, endpoint, init);
   } catch (error) {
     const server = (process.env.STMA_URL ?? config.server ?? "http://localhost:3000").replace(/\/$/, "");
-    fail(`Request to ${server} failed: ${error instanceof Error ? error.message : String(error)}`);
+    const status = error.status;
+    const note = status === 404 ? await skewNote(server) : "";
+    fail(`Request to ${server} failed: ${error instanceof Error ? error.message : String(error)}${note}`);
   }
 }
 function printConflicts(conflicts) {
@@ -4515,7 +5005,7 @@ async function register(flags) {
   const config = loadConfig();
   const name = required(flags, "name");
   const clientType = one(flags, "client") ?? "generic";
-  const rawDevice = `${os.hostname()}\0${os.userInfo().username}\0${process.platform}`;
+  const rawDevice = `${os2.hostname()}\0${os2.userInfo().username}\0${process.platform}`;
   const deviceFingerprint = sha256(rawDevice);
   const result = await request(config, "/api/agent/installations/register", {
     method: "POST",
@@ -4524,7 +5014,8 @@ async function register(flags) {
       clientType,
       clientVersion: one(flags, "version"),
       deviceFingerprint,
-      capabilities: all(flags, "capability")
+      capabilities: all(flags, "capability"),
+      role: one(flags, "role")
     })
   });
   saveConfig({
@@ -4554,9 +5045,10 @@ async function startRun(flags) {
       intent: one(flags, "intent"),
       repo: one(flags, "repo") ?? project ?? git.repo,
       branch: one(flags, "branch") ?? git.branch,
-      worktree: git.worktree,
+      worktree: one(flags, "worktree") ?? git.worktree,
       baseSha: git.baseSha,
-      claims
+      claims,
+      attemptGroup: one(flags, "attempt-group")
     })
   });
   saveConfig({
@@ -4589,10 +5081,53 @@ async function heartbeat(flags) {
   );
   const result = await request(config, `/api/agent/runs/${runId}/heartbeat`, {
     method: "POST",
-    body: JSON.stringify({ status: one(flags, "status"), claims })
+    body: JSON.stringify({ status: one(flags, "status"), claims, usage: quotaFlags(flags) })
   });
   console.log(`Heartbeat: ${result.status}`);
   printConflicts(result.conflicts ?? []);
+  printQuota(result);
+}
+function hookQuota(payload) {
+  const fromPayload = payload.usage ?? payload.quota;
+  if (fromPayload && typeof fromPayload === "object") {
+    const u = fromPayload;
+    const pct = Number(u.usedPct ?? u.used_pct ?? u.percent_used);
+    if (Number.isFinite(pct) && pct >= 0 && pct <= 100) {
+      return {
+        usedPct: pct,
+        resetsAt: typeof u.resetsAt === "string" ? u.resetsAt : void 0,
+        label: typeof u.label === "string" ? u.label : void 0
+      };
+    }
+  }
+  const env = Number(process.env.STMA_USED_PCT);
+  if (!Number.isFinite(env) || env < 0 || env > 100) return void 0;
+  return {
+    usedPct: env,
+    resetsAt: process.env.STMA_QUOTA_RESETS_AT || void 0,
+    label: process.env.STMA_QUOTA_LABEL || void 0
+  };
+}
+function quotaFlags(flags) {
+  const raw = one(flags, "used-pct");
+  if (raw === void 0) return void 0;
+  const usedPct = Number(raw);
+  if (!Number.isFinite(usedPct) || usedPct < 0 || usedPct > 100) {
+    fail("--used-pct must be a number between 0 and 100.");
+  }
+  return {
+    usedPct,
+    resetsAt: one(flags, "resets-at"),
+    label: one(flags, "quota-label")
+  };
+}
+function printQuota(result) {
+  const quota = result?.quota;
+  if (!quota || quota.state === "ok") return;
+  console.log(
+    `${quota.state === "critical" ? "QUOTA CRITICAL" : "Quota warning"}: ${quota.usedPct}% used${quota.label ? ` (${quota.label})` : ""}`
+  );
+  if (quota.advice) console.log(`  ${quota.advice}`);
 }
 async function finish(flags) {
   const config = loadConfig();
@@ -4615,17 +5150,17 @@ async function listRuns(flags) {
   const team = one(flags, "team");
   const result = await request(config, `/api/agent/runs/active${team ? `?team=${encodeURIComponent(team)}` : ""}`);
   if (result.runs.length === 0) return console.log("No active runs.");
-  for (const run of result.runs) {
+  for (const run2 of result.runs) {
     console.log(
-      `${run.id}  ${run.owner}/${run.installation.name}  ${run.team}/${run.project ?? "\u2014"}  ${run.taskKey ?? "no-task"}  ${run.status}  ${run.branch ?? "\u2014"}`
+      `${run2.id}  ${run2.owner}/${run2.installation.name}  ${run2.team}/${run2.project ?? "\u2014"}  ${run2.taskKey ?? "no-task"}  ${run2.status}  ${run2.branch ?? "\u2014"}`
     );
   }
 }
 async function publishPolicy(flags) {
   const config = loadConfig();
-  const file = one(flags, "file") ?? path3.join(stmaDir, "policy.json");
-  if (!existsSync3(file)) fail(`Policy file not found: ${file}`);
-  const document = JSON.parse(readFileSync3(file, "utf8"));
+  const file = one(flags, "file") ?? path5.join(stmaDir, "policy.json");
+  if (!existsSync5(file)) fail(`Policy file not found: ${file}`);
+  const document = JSON.parse(readFileSync5(file, "utf8"));
   const result = await request(config, "/api/control/policies", {
     method: "POST",
     body: JSON.stringify({
@@ -4676,7 +5211,7 @@ async function execRun(flags, command) {
     heartbeatBusy = true;
     void heartbeat(/* @__PURE__ */ new Map([["run", [runId]]])).finally(() => heartbeatBusy = false);
   }, 6e4);
-  const child = spawn(command[0], command.slice(1), { cwd, stdio: "inherit", env: process.env });
+  const child = spawn2(command[0], command.slice(1), { cwd, stdio: "inherit", env: process.env });
   const code = await new Promise((resolve) => {
     child.on("exit", (value) => resolve(value ?? 1));
     child.on("error", () => resolve(1));
@@ -4697,7 +5232,7 @@ function adapterInstall(flags) {
     target,
     team: required(flags, "team"),
     project: one(flags, "project"),
-    agentName: one(flags, "name") ?? `${os.userInfo().username}-${target}`,
+    agentName: one(flags, "name") ?? `${os2.userInfo().username}-${target}`,
     defaultTask: one(flags, "task"),
     defaultIntent: one(flags, "intent"),
     applyPolicy: one(flags, "policy") !== "false",
@@ -4729,7 +5264,7 @@ function adapterInstall(flags) {
 }
 function readHookPayload() {
   if (process.stdin.isTTY) return {};
-  const raw = readFileSync3(0, "utf8");
+  const raw = readFileSync5(0, "utf8");
   if (!raw.trim()) return {};
   if (raw.length > 1e6) throw new Error("Hook input exceeds 1 MB.");
   const value = JSON.parse(raw);
@@ -4749,9 +5284,9 @@ function hookIntent(adapter, payload) {
   return adapter.defaultIntent;
 }
 function loadOutbox() {
-  if (!existsSync3(outboxPath)) return [];
+  if (!existsSync5(outboxPath)) return [];
   try {
-    const data = JSON.parse(readFileSync3(outboxPath, "utf8"));
+    const data = JSON.parse(readFileSync5(outboxPath, "utf8"));
     return Array.isArray(data) ? data.slice(-500) : [];
   } catch {
     return [];
@@ -4764,7 +5299,7 @@ function saveOutbox(events) {
 }
 async function ensureAdapterInstallation(adapter) {
   const local = loadConfig();
-  const rawDevice = `${os.hostname()}\0${os.userInfo().username}\0${process.platform}\0${adapter.target}`;
+  const rawDevice = `${os2.hostname()}\0${os2.userInfo().username}\0${process.platform}\0${adapter.target}`;
   const result = await apiRequest(local, "/api/agent/installations/register", {
     method: "POST",
     body: JSON.stringify({
@@ -4858,10 +5393,19 @@ async function processHookEvent(event) {
   }
   if (!runId) return void 0;
   if (event.event === "heartbeat") {
-    await apiRequest(local, `/api/agent/runs/${runId}/heartbeat`, {
+    const observed = nativeClaims();
+    const usage = hookQuota(event.payload);
+    const result = await apiRequest(local, `/api/agent/runs/${runId}/heartbeat`, {
       method: "POST",
-      body: JSON.stringify({ status: "active", claims: nativeClaims() })
+      body: JSON.stringify({
+        status: "active",
+        ...observed.length > 0 ? { claims: observed } : {},
+        ...usage ? { usage } : {}
+      })
     });
+    if (result?.quota && result.quota.state !== "ok" && result.quota.advice) {
+      console.error(`[stma] ${result.quota.advice}`);
+    }
     return void 0;
   }
   await apiRequest(local, `/api/agent/runs/${runId}/finish`, {
@@ -4893,6 +5437,10 @@ function hookOutput(target, notice) {
     console.log(JSON.stringify({ continue: true, user_message: notice }));
   }
 }
+function isPermanentHookFailure(error) {
+  const status = error?.status;
+  return typeof status === "number" && status >= 400 && status < 500;
+}
 async function adapterHook(flags) {
   const value = required(flags, "event");
   if (!["start", "heartbeat", "finish"].includes(value)) fail("Invalid adapter hook event.");
@@ -4923,25 +5471,117 @@ async function adapterHook(flags) {
     try {
       const result = await processHookEvent(item);
       if (item.id === current.id) notice = result;
-    } catch {
+    } catch (error) {
+      if (isPermanentHookFailure(error)) continue;
       failed = true;
       remaining.push(item);
     }
   }
   saveOutbox(remaining);
-  hookOutput(adapter.target, notice);
+  const waiting = await newsNotice();
+  hookOutput(adapter.target, [notice, waiting].filter(Boolean).join("\n\n") || void 0);
+}
+async function newsNotice() {
+  try {
+    const config = loadConfig();
+    if (!dueForCheck({ lastCheckedAt: config.newsCheckedAt, announced: config.newsAnnounced })) {
+      return void 0;
+    }
+    const { server, token } = connection(config);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), NEWS_TIMEOUT_MS);
+    let news;
+    try {
+      const response = await fetch(`${server}/api/agent/news`, {
+        headers: { authorization: `Bearer ${token}`, ...clientHeaders() },
+        signal: controller.signal
+      });
+      if (!response.ok) return void 0;
+      news = await response.json();
+    } finally {
+      clearTimeout(timer);
+    }
+    const state = { lastCheckedAt: config.newsCheckedAt, announced: config.newsAnnounced };
+    const fresh = unseen(news, state);
+    saveConfig({
+      ...config,
+      newsCheckedAt: news.checkedAt,
+      newsAnnounced: rememberAnnounced(state, fresh)
+    });
+    return renderNews(fresh, news.unreadSessions);
+  } catch {
+    return void 0;
+  }
+}
+async function watch(flags) {
+  const seconds = Number(one(flags, "interval") ?? 30);
+  if (!Number.isFinite(seconds) || seconds < 10 || seconds > 3600) {
+    fail(`--interval must be between 10 and 3600 seconds (got ${one(flags, "interval")}).`);
+  }
+  const config = loadConfig();
+  const { server, token } = connection(config);
+  const announced = /* @__PURE__ */ new Set();
+  let firstPass = true;
+  console.log(`stma: watching ${server} every ${seconds}s. Ctrl+C to stop.`);
+  for (; ; ) {
+    try {
+      const response = await fetch(`${server}/api/agent/news`, {
+        headers: { authorization: `Bearer ${token}`, ...clientHeaders() }
+      });
+      if (response.ok) {
+        const news = await response.json();
+        for (const handoff of news.pendingHandoffs) {
+          const key = handoffKey(handoff);
+          if (announced.has(key)) continue;
+          announced.add(key);
+          const who = handoff.mine ? "your other machine" : handoff.from ?? "a teammate";
+          const line = `work waiting \u2014 "${handoff.title}" from ${who}${handoff.resume?.branch ? ` on ${handoff.resume.branch}` : ""}`;
+          console.log(`${(/* @__PURE__ */ new Date()).toISOString().slice(11, 19)}  ${line}`);
+          if (!firstPass) notifyDesktop("STMA", line);
+        }
+      }
+    } catch {
+    }
+    firstPass = false;
+    await new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+  }
+}
+function notifyDesktop(title, body) {
+  try {
+    if (process.platform === "darwin") {
+      execFileSync2("osascript", ["-e", `display notification "${body}" with title "${title}"`], {
+        stdio: "ignore"
+      });
+    } else if (process.platform === "win32") {
+      execFileSync2(
+        "powershell",
+        ["-NoProfile", "-Command", `[console]::beep(880,150)`],
+        { stdio: "ignore" }
+      );
+    } else {
+      execFileSync2("notify-send", [title, body], { stdio: "ignore" });
+    }
+  } catch {
+  }
 }
 function help() {
-  console.log(`STMA local control-plane CLI
+  console.log(`STMA local control-plane CLI ${VERSION}
 
 Environment:
   STMA_URL=http://localhost:3000
   STMA_TOKEN=stma_...
 
 Commands:
-  stma agent register --name NAME [--client generic]
+  stma serve [--port 3000] [--host 127.0.0.1] [--data DIR]
+             Run a private instance on this machine \u2014 embedded database, no setup.
+  stma watch [--interval 30]
+             Say when work is handed to you, while you are not at the keyboard.
+  stma agent register --name NAME [--client generic] [--role implementer|reviewer|tester|planner|ops]
   stma run start --team TEAM [--project PROJECT] [--task KEY] [--scope path]
+                 [--attempt-group KEY]   parallel attempts at one task never warn each other
   stma run heartbeat [--status active|waiting|blocked]
+                     [--used-pct N] [--resets-at ISO] [--quota-label TEXT]
+                     report your own vendor allowance; STMA answers with when to hand off
   stma run finish [--status completed|failed]
   stma run list [--team TEAM]
   stma run exec --team TEAM [run options] -- <agent command>
@@ -4951,10 +5591,43 @@ Commands:
   stma env preflight --team TEAM --project PROJECT
   stma adapter install --target claude-code|codex|cursor --team TEAM [--project PROJECT]
                        [--name NAME] [--command stma] [--policy=false] [--preflight=false] [--apply]
+  stma version [--server]   this CLI's version, and optionally the server's
 `);
 }
+async function version(flags) {
+  console.log(`stma ${VERSION}`);
+  if (!flags.has("server")) return;
+  const server = (process.env.STMA_URL ?? loadConfig().server ?? "http://localhost:3000").replace(/\/$/, "");
+  try {
+    const res = await fetch(`${server}/health`, { signal: AbortSignal.timeout(5e3) });
+    const health = await res.json();
+    console.log(`server ${health.version ?? "unknown"} (${server})`);
+    if (health.version && health.version !== VERSION) {
+      console.log("note: client and server versions differ \u2014 features added since the older one will be missing.");
+    }
+  } catch (error) {
+    console.log(`server unreachable (${server}): ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
 async function main() {
-  const [group, action, ...rest] = process.argv.slice(2);
+  const argv = process.argv.slice(2);
+  const [group, action, ...rest] = argv;
+  if (group === "version" || group === "--version" || group === "-v") {
+    return version(parseFlags(argv.slice(1)).flags);
+  }
+  if (group === "watch") return watch(parseFlags(argv.slice(1)).flags);
+  if (group === "serve") {
+    const serveFlags = parseFlags(argv.slice(1)).flags;
+    const port = Number(one(serveFlags, "port") ?? 3e3);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      fail(`--port must be a port number (got ${one(serveFlags, "port")}).`);
+    }
+    return serve({
+      port,
+      host: one(serveFlags, "host") ?? "127.0.0.1",
+      dataDir: one(serveFlags, "data") ?? defaultDataDir()
+    });
+  }
   const { flags, passthrough } = parseFlags(rest);
   if (group === "agent" && action === "register") return register(flags);
   if (group === "run" && action === "start") return void await startRun(flags);