@usezombie/zombiectl 0.3.0

package/README.md

@@ -0,0 +1,76 @@
+# zombiectl
+
+JavaScript CLI for UseZombie operator workflows.
+
+Local state lives in `~/.config/zombiectl/` by default:
+- `credentials.json` — auth/session state
+- `workspaces.json` — current workspace selection and local cache
+- `ZOMBIE_STATE_DIR` overrides the base directory for tests or custom automation
+
+## Install
+
+```bash
+npm install -g @usezombie/zombiectl
+zombiectl --help
+```
+
+## Usage
+
+Common flows (installed binary):
+
+```bash
+zombiectl login
+zombiectl workspace add https://github.com/org/repo
+zombiectl specs sync
+zombiectl run
+zombiectl run status <run_id>
+zombiectl doctor --json
+```
+
+Operator trajectory flow:
+
+```bash
+zombiectl agent profile <agent-id>
+zombiectl agent improvement-report <agent-id>
+zombiectl agent proposals <agent-id>
+zombiectl agent proposals <agent-id> veto <proposal-id> --reason "operator pause"
+```
+
+`workspace add` opens the UseZombie GitHub App install page and binds workspace via callback automatically.
+Global flags:
+- `--api <url>` API base URL (default `http://localhost:3000`)
+- `--json` machine-readable output
+- `--no-open` do not auto-open browser on login
+- `--no-input` disable prompts (reserved for non-interactive flows)
+- `--help`
+- `--version`
+
+Analytics env vars (optional):
+- `ZOMBIE_POSTHOG_KEY` override the bundled PostHog project API key (`phc_...`) for local/dev testing
+- `ZOMBIE_POSTHOG_ENABLED` set `false`/`0` to disable telemetry even when the bundled key exists
+- `ZOMBIE_POSTHOG_HOST` override PostHog host (default `https://us.i.posthog.com`)
+
+Standard operator path:
+
+```bash
+# DEV
+export ZOMBIE_POSTHOG_KEY="$(op read 'op://ZMB_CD_DEV/posthog-dev/credential')"
+
+# PROD
+export ZOMBIE_POSTHOG_KEY="$(op read 'op://ZMB_CD_PROD/posthog-prod/credential')"
+```
+
+This follows the same milestone playbook and `scripts/check-credentials.sh` contract as the other deploy/runtime keys.
+
+Analytics key policy:
+- `zombiectl` ships with a bundled default PostHog project key so end users do not need analytics setup after `npm install -g`.
+- The bundled key is not an auth secret; it is a write-scoped ingestion key.
+- Do not persist analytics keys in CLI auth/session state such as `credentials.json`.
+- If exposed, the expected risk is analytics pollution or noisy metrics, not control-plane access.
+
+## Verify
+
+```bash
+bun test
+bun run build
+```

package/bin/zombiectl.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.js";
+
+const exitCode = await runCli(process.argv.slice(2), {
+  env: process.env,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  stdin: process.stdin,
+});
+
+process.exit(exitCode);

package/bun.lock

@@ -0,0 +1,29 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "zombiectl",
+      "dependencies": {
+        "posthog-node": "^5.10.0",
+      },
+    },
+  },
+  "packages": {
+    "@posthog/core": ["@posthog/core@1.23.3", "", { "dependencies": { "cross-spawn": "^7.0.6" } }, "sha512-nehG2nig9qiU4lEUIyfXQLaBnylm5wdDiIBsp2tBFJX5BcUHNAXSwpkHjKLQ9TDfik0HW1HwZ2mY/3hJgJNToQ=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
+    "posthog-node": ["posthog-node@5.28.1", "", { "dependencies": { "@posthog/core": "1.23.3" }, "peerDependencies": { "rxjs": "^7.0.0" }, "optionalPeers": ["rxjs"] }, "sha512-dfUaeNwKc/YZI/vbP5IJSMuMprPLbtzWM/ZQFkuyWj0fhU3PW0VmxNO1gkqy48SsUauamczEPBKTQRYZVLcacg=="],
+
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+  }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@usezombie/zombiectl",
+  "version": "0.3.0",
+  "description": "UseZombie CLI",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usezombie/usezombie"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "zombiectl": "./bin/zombiectl.js"
+  },
+  "engines": {
+    "node": ">=24.0.0",
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "test": "node ./scripts/run-tests.mjs",
+    "build": "node --check ./src/cli.js && node --check ./bin/zombiectl.js"
+  },
+  "dependencies": {
+    "posthog-node": "^5.10.0"
+  },
+  "license": "MIT"
+}

package/scripts/run-tests.mjs

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const testDir = path.resolve("test");
+const files = fs.readdirSync(testDir)
+  .filter((file) => file.endsWith(".js"))
+  .map((file) => path.join("test", file))
+  .sort();
+
+const nodeTests = [];
+const bunTests = [];
+
+for (const file of files) {
+  const source = fs.readFileSync(path.resolve(file), "utf8");
+  if (source.includes('from "node:test"') || source.includes("from 'node:test'")) {
+    nodeTests.push(file);
+    continue;
+  }
+  if (source.includes('from "bun:test"') || source.includes("from 'bun:test'")) {
+    bunTests.push(file);
+  }
+}
+
+function run(command, args) {
+  if (args.length === 0) return;
+  const result = spawnSync(command, args, {
+    stdio: "inherit",
+    cwd: process.cwd(),
+    env: process.env,
+  });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+run("node", ["--test", ...nodeTests]);
+run("bun", ["test", ...bunTests]);

package/src/cli.js

@@ -0,0 +1,275 @@
+import { openUrl } from "./lib/browser.js";
+import {
+  cliAnalytics,
+  drainCliAnalyticsEvents,
+  getCliAnalyticsContext,
+} from "./lib/analytics.js";
+import { findRoute } from "./program/routes.js";
+import { registerProgramCommands } from "./program/command-registry.js";
+import { commandHarness as commandHarnessModule } from "./commands/harness.js";
+import { commandAgent as commandAgentModule } from "./commands/agent.js";
+import { commandAdmin as commandAdminModule } from "./commands/admin.js";
+import { commandRuns as commandRunsModule } from "./commands/runs.js";
+import { ui, printKeyValue, printSection, printTable } from "./ui-theme.js";
+import { createSpinner } from "./ui-progress.js";
+import {
+  clearCredentials,
+  loadCredentials,
+  loadWorkspaces,
+  newIdempotencyKey,
+  saveCredentials,
+  saveWorkspaces,
+} from "./lib/state.js";
+import { ApiError, apiHeaders, printApiError, request } from "./program/http-client.js";
+import { parseFlags, parseGlobalArgs, normalizeApiUrl, DEFAULT_API_URL } from "./program/args.js";
+import { extractDistinctIdFromToken, extractRoleFromToken } from "./program/auth-token.js";
+import { printHelp, printJson, writeLine } from "./program/io.js";
+import { printBanner, printPreReleaseWarning } from "./program/banner.js";
+import { suggestCommand } from "./program/suggest.js";
+import { requireAuth, AUTH_FAIL_MESSAGE } from "./program/auth-guard.js";
+import { createCoreHandlers } from "./commands/core.js";
+
+export const VERSION = "0.3.0";
+
+export { parseGlobalArgs };
+
+const AUTH_EXEMPT_ROUTES = new Set(["login", "doctor", "spec.init"]);
+
+export async function runCli(argv, io = {}) {
+  const stdout = io.stdout || process.stdout;
+  const stderr = io.stderr || process.stderr;
+  const env = io.env || process.env;
+  const fetchImpl = io.fetchImpl || globalThis.fetch;
+
+  const { global, rest } = parseGlobalArgs(argv, env);
+  const noColor = Boolean(env.NO_COLOR === "1" || env.NO_COLOR === "true");
+
+  printPreReleaseWarning(stderr, { noColor, jsonMode: global.json, ttyOnly: !stderr.isTTY });
+
+  if (global.version) {
+    if (global.json) {
+      printJson(stdout, { version: VERSION });
+    } else {
+      printBanner(stdout, VERSION, { noColor, jsonMode: false });
+    }
+    return 0;
+  }
+
+  const creds = await loadCredentials().catch(() => ({}));
+  const workspaces = await loadWorkspaces().catch(() => ({ items: [], current_workspace_id: null }));
+  const resolvedToken = creds.token || env.ZOMBIE_TOKEN || null;
+  const resolvedApiKey = env.API_KEY || env.ZOMBIE_API_KEY || null;
+  const resolvedAuthRole = extractRoleFromToken(resolvedToken) || (resolvedApiKey ? "admin" : null);
+
+  if (global.help || rest.length === 0) {
+    printHelp(stdout, ui, {
+      version: VERSION,
+      env,
+      jsonMode: global.json,
+      authRole: resolvedAuthRole,
+    });
+    return 0;
+  }
+
+  const ctx = {
+    apiUrl: normalizeApiUrl(global.apiUrl || creds.api_url || DEFAULT_API_URL),
+    token: resolvedToken,
+    apiKey: resolvedApiKey,
+    authRole: resolvedAuthRole,
+    jsonMode: global.json,
+    noOpen: global.noOpen,
+    noInput: global.noInput,
+    stdout,
+    stderr,
+    env,
+    fetchImpl,
+  };
+
+  const command = rest[0];
+  const args = rest.slice(1);
+  const route = findRoute(command, args);
+
+  // Auth guard: skip for login, doctor, help, version
+  if (route && !AUTH_EXEMPT_ROUTES.has(route.key)) {
+    const auth = requireAuth(ctx);
+    if (!auth.ok) {
+      if (ctx.jsonMode) {
+        printJson(stderr, { error: { code: "AUTH_REQUIRED", message: AUTH_FAIL_MESSAGE } });
+      } else {
+        writeLine(stderr, ui.err(AUTH_FAIL_MESSAGE));
+      }
+      return 1;
+    }
+  }
+
+  const core = createCoreHandlers(ctx, workspaces, {
+    clearCredentials,
+    createSpinner,
+    newIdempotencyKey,
+    openUrl,
+    parseFlags,
+    printJson,
+    printKeyValue,
+    printSection,
+    printTable,
+    request,
+    saveCredentials,
+    saveWorkspaces,
+    ui,
+    writeLine,
+    apiHeaders,
+  });
+
+  const analyticsClient = await cliAnalytics.createCliAnalytics(env);
+  const distinctId = extractDistinctIdFromToken(ctx.token);
+
+  const handlers = registerProgramCommands({
+    login: (routeArgs) => core.commandLogin(routeArgs),
+    logout: () => core.commandLogout(),
+    workspace: (routeArgs) => core.commandWorkspace(routeArgs),
+    specInit: (routeArgs) => core.commandSpecInit(routeArgs.slice(1)),
+    specsSync: (routeArgs) => core.commandSpecsSync(routeArgs.slice(1)),
+    run: (routeArgs) => core.commandRun(routeArgs),
+    runsList: (routeArgs) => core.commandRunsList(routeArgs.slice(1)),
+    doctor: () => core.commandDoctor(),
+    harness: (routeArgs) => commandHarnessModule(ctx, routeArgs, workspaces, {
+      parseFlags,
+      request,
+      apiHeaders,
+      ui,
+      printJson,
+      printKeyValue,
+      printSection,
+      writeLine,
+    }),
+    skillSecret: (routeArgs) => core.commandSkillSecret(routeArgs),
+    agent: (routeArgs) => commandAgentModule(ctx, routeArgs, workspaces, {
+      parseFlags,
+      request,
+      apiHeaders,
+      ui,
+      printJson,
+      printKeyValue,
+      printSection,
+      printTable,
+      writeLine,
+    }),
+    admin: (routeArgs) => commandAdminModule(ctx, routeArgs, workspaces, {
+      parseFlags,
+      request,
+      apiHeaders,
+      ui,
+      printJson,
+      printSection,
+      writeLine,
+    }),
+    runsCancel: (routeArgs) => commandRunsModule(ctx, routeArgs, {
+      parseFlags,
+      request,
+      apiHeaders,
+      ui,
+      printJson,
+      writeLine,
+    }),
+  });
+
+  try {
+    if (route && handlers[route.key]) {
+      cliAnalytics.trackCliEvent(analyticsClient, distinctId, "cli_command_started", {
+        command: route.key,
+        json_mode: String(ctx.jsonMode),
+      });
+
+      const exitCode = await handlers[route.key](args);
+      const analyticsContext = getCliAnalyticsContext(ctx);
+      let eventDistinctId = distinctId;
+      if (exitCode === 0 && route.key === "login") {
+        const latestCreds = await loadCredentials();
+        eventDistinctId = extractDistinctIdFromToken(latestCreds.token) || distinctId;
+      }
+      cliAnalytics.trackCliEvent(analyticsClient, distinctId, "cli_command_finished", {
+        command: route.key,
+        exit_code: String(exitCode),
+        ...analyticsContext,
+      });
+
+      if (exitCode === 0 && route.key === "login") {
+        cliAnalytics.trackCliEvent(analyticsClient, eventDistinctId, "user_authenticated", {
+          command: route.key,
+          ...analyticsContext,
+        });
+      }
+      if (exitCode === 0 && route.key === "workspace" && args[0] === "add") {
+        cliAnalytics.trackCliEvent(analyticsClient, distinctId, "workspace_created", {
+          command: route.key,
+          ...analyticsContext,
+        });
+      }
+      if (exitCode === 0 && route.key === "run" && args[0] !== "status") {
+        cliAnalytics.trackCliEvent(analyticsClient, distinctId, "run_triggered", {
+          command: route.key,
+          ...analyticsContext,
+        });
+      }
+      for (const queuedEvent of drainCliAnalyticsEvents(ctx)) {
+        cliAnalytics.trackCliEvent(analyticsClient, eventDistinctId, queuedEvent.event, {
+          command: route.key,
+          ...analyticsContext,
+          ...queuedEvent.properties,
+        });
+      }
+      if (exitCode !== 0) {
+        cliAnalytics.trackCliEvent(analyticsClient, distinctId, "cli_error", {
+          command: route.key,
+          exit_code: String(exitCode),
+          ...analyticsContext,
+        });
+      }
+      return exitCode;
+    }
+
+    // "Did you mean?" suggestion for unknown commands
+    const fullInput = [command, ...args].join(" ");
+    const suggestions = suggestCommand(fullInput);
+    if (suggestions.length > 0) {
+      writeLine(stderr, ui.err(`unknown command: ${command}`));
+      writeLine(stderr);
+      writeLine(stderr, "The most similar commands are");
+      for (const s of suggestions) {
+        writeLine(stderr, `    ${s}`);
+      }
+    } else {
+      writeLine(stderr, ui.err(`unknown command: ${command}`));
+      writeLine(stderr, `Run 'zombiectl --help' for usage.`);
+    }
+
+    cliAnalytics.trackCliEvent(analyticsClient, distinctId, "cli_error", {
+      command,
+      error_code: "UNKNOWN_COMMAND",
+      exit_code: "2",
+      ...getCliAnalyticsContext(ctx),
+    });
+    return 2;
+  } catch (err) {
+    const errorCode = err instanceof ApiError ? err.code || "API_ERROR" : "UNEXPECTED";
+    cliAnalytics.trackCliEvent(analyticsClient, distinctId, "cli_error", {
+      command: route?.key || command || "unknown",
+      error_code: errorCode,
+      exit_code: "1",
+      ...getCliAnalyticsContext(ctx),
+    });
+    try {
+      printApiError(stderr, err, global.json, printJson, writeLine);
+      return 1;
+    } catch {
+      if (global.json) {
+        printJson(stderr, { error: { code: "UNEXPECTED", message: String(err) } });
+      } else {
+        writeLine(stderr, `error: ${String(err)}`);
+      }
+      return 1;
+    }
+  } finally {
+    await cliAnalytics.shutdownCliAnalytics(analyticsClient);
+  }
+}

package/src/commands/admin.js

@@ -0,0 +1,39 @@
+export async function commandAdmin(ctx, args, workspaces, deps) {
+  const { parseFlags, ui, writeLine } = deps;
+  const group = args[0];
+  const action = args[1];
+  const key = args[2];
+  const parsed = parseFlags(args.slice(3));
+
+  if (group === "config" && action === "set" && key === "scoring_context_max_tokens") {
+    const workspaceId = parsed.options["workspace-id"];
+    const rawValue = parsed.positionals[0] || parsed.options.value;
+    if (!workspaceId) {
+      writeLine(ctx.stderr, ui.err("admin config set scoring_context_max_tokens requires --workspace-id"));
+      return 2;
+    }
+    if (!rawValue) {
+      writeLine(ctx.stderr, ui.err("admin config set scoring_context_max_tokens requires <value>"));
+      return 2;
+    }
+    const parsedValue = Number.parseInt(rawValue, 10);
+    if (!Number.isInteger(parsedValue) || parsedValue < 512 || parsedValue > 8192) {
+      writeLine(ctx.stderr, ui.err("scoring_context_max_tokens must be an integer between 512 and 8192"));
+      return 2;
+    }
+    const res = await deps.request(ctx, `/v1/workspaces/${encodeURIComponent(workspaceId)}/scoring/config`, {
+      method: "POST",
+      headers: deps.apiHeaders(ctx),
+      body: JSON.stringify({ scoring_context_max_tokens: parsedValue }),
+    });
+    if (ctx.jsonMode) {
+      deps.printJson(ctx.stdout, res);
+    } else {
+      writeLine(ctx.stdout, ui.ok(`workspace scoring_context_max_tokens=${res.scoring_context_max_tokens}`));
+    }
+    return 0;
+  }
+
+  writeLine(ctx.stderr, ui.err("usage: admin config set scoring_context_max_tokens <value> --workspace-id ID"));
+  return 2;
+}

package/src/commands/agent.js

@@ -0,0 +1,98 @@
+import { setCliAnalyticsContext } from "../lib/analytics.js";
+import { commandAgentScores } from "./agent_scores.js";
+import { commandAgentProfile } from "./agent_profile.js";
+import { commandAgentImprovementReport } from "./agent_improvement_report.js";
+import { commandAgentProposals } from "./agent_proposals.js";
+import { commandAgentHarness } from "./agent_harness.js";
+import { validateRequiredId } from "../program/validate.js";
+
+export async function commandAgent(ctx, args, workspaces, deps) {
+  const { parseFlags, ui, writeLine } = deps;
+
+  const action = args[0];
+  const parsed = parseFlags(args.slice(1));
+  const agentId = parsed.positionals[0] || parsed.options["agent-id"];
+  if (agentId) setCliAnalyticsContext(ctx, { agent_id: agentId });
+
+  if (action === "scores") {
+    if (!agentId) {
+      writeLine(ctx.stderr, ui.err("agent scores requires <agent-id>"));
+      return 2;
+    }
+    const check = validateRequiredId(agentId, "agent-id");
+    if (!check.ok) {
+      writeLine(ctx.stderr, ui.err(check.message));
+      return 2;
+    }
+    return commandAgentScores(ctx, parsed, agentId, deps);
+  }
+
+  if (action === "profile") {
+    if (!agentId) {
+      writeLine(ctx.stderr, ui.err("agent profile requires <agent-id>"));
+      return 2;
+    }
+    const check = validateRequiredId(agentId, "agent-id");
+    if (!check.ok) {
+      writeLine(ctx.stderr, ui.err(check.message));
+      return 2;
+    }
+    return commandAgentProfile(ctx, parsed, agentId, deps);
+  }
+
+  if (action === "improvement-report") {
+    if (!agentId) {
+      writeLine(ctx.stderr, ui.err("agent improvement-report requires <agent-id>"));
+      return 2;
+    }
+    const check = validateRequiredId(agentId, "agent-id");
+    if (!check.ok) {
+      writeLine(ctx.stderr, ui.err(check.message));
+      return 2;
+    }
+    return commandAgentImprovementReport(ctx, parsed, agentId, deps);
+  }
+
+  if (action === "proposals") {
+    if (!agentId) {
+      writeLine(ctx.stderr, ui.err("agent proposals requires <agent-id>"));
+      return 2;
+    }
+    const check = validateRequiredId(agentId, "agent-id");
+    if (!check.ok) {
+      writeLine(ctx.stderr, ui.err(check.message));
+      return 2;
+    }
+    return commandAgentProposals(ctx, parsed, agentId, deps);
+  }
+
+  if (action === "harness") {
+    if (!agentId) {
+      writeLine(ctx.stderr, ui.err("agent harness revert requires <agent-id>"));
+      return 2;
+    }
+    const check = validateRequiredId(agentId, "agent-id");
+    if (!check.ok) {
+      writeLine(ctx.stderr, ui.err(check.message));
+      return 2;
+    }
+    const changeId = parsed.options["to-change"];
+    if (!changeId) {
+      writeLine(ctx.stderr, ui.err("agent harness revert requires --to-change <change-id>"));
+      return 2;
+    }
+    const changeCheck = validateRequiredId(changeId, "change-id");
+    if (!changeCheck.ok) {
+      writeLine(ctx.stderr, ui.err(changeCheck.message));
+      return 2;
+    }
+    return commandAgentHarness(ctx, parsed, agentId, deps);
+  }
+
+  writeLine(ctx.stderr, ui.err("usage: agent scores <agent-id> [--limit N] [--starting-after ID] [--json]"));
+  writeLine(ctx.stderr, ui.err("       agent profile <agent-id> [--json]"));
+  writeLine(ctx.stderr, ui.err("       agent improvement-report <agent-id> [--json]"));
+  writeLine(ctx.stderr, ui.err("       agent proposals <agent-id> [approve <proposal-id> | reject <proposal-id> [--reason TEXT] | veto <proposal-id> [--reason TEXT] | --json]"));
+  writeLine(ctx.stderr, ui.err("       agent harness revert <agent-id> --to-change <change-id>"));
+  return 2;
+}

package/src/commands/agent_harness.js

@@ -0,0 +1,43 @@
+import { AGENTS_PATH } from "../lib/api-paths.js";
+import { queueCliAnalyticsEvent, setCliAnalyticsContext } from "../lib/analytics.js";
+
+export async function commandAgentHarness(ctx, parsed, agentId, deps) {
+  const { request, apiHeaders, printJson, ui, writeLine } = deps;
+
+  const subaction = parsed.positionals[0] || null;
+  if (subaction !== "revert") {
+    writeLine(ctx.stderr, ui.err("usage: agent harness revert <agent-id> --to-change <change-id>"));
+    return 2;
+  }
+
+  const changeId = parsed.options["to-change"] || null;
+  if (!changeId) {
+    writeLine(ctx.stderr, ui.err("agent harness revert requires --to-change <change-id>"));
+    return 2;
+  }
+
+  const res = await request(
+    ctx,
+    `${AGENTS_PATH}${encodeURIComponent(agentId)}/harness/changes/${encodeURIComponent(changeId)}:revert`,
+    {
+      method: "POST",
+      headers: apiHeaders(ctx),
+    },
+  );
+  setCliAnalyticsContext(ctx, {
+    agent_id: agentId,
+    change_id: res.change_id,
+    reverted_from: res.reverted_from,
+  });
+  queueCliAnalyticsEvent(ctx, "agent_harness_reverted", {
+    agent_id: agentId,
+    change_id: res.change_id,
+  });
+
+  if (ctx.jsonMode) {
+    printJson(ctx.stdout, res);
+  } else {
+    writeLine(ctx.stdout, ui.ok(`reverted ${res.reverted_from} -> ${res.change_id}`));
+  }
+  return 0;
+}

package/src/commands/agent_improvement_report.js

@@ -0,0 +1,42 @@
+import { AGENTS_PATH } from "../lib/api-paths.js";
+import { queueCliAnalyticsEvent, setCliAnalyticsContext } from "../lib/analytics.js";
+
+export async function commandAgentImprovementReport(ctx, parsed, agentId, deps) {
+  const { request, apiHeaders, printJson, printKeyValue, printSection = () => {} } = deps;
+
+  const res = await request(ctx, `${AGENTS_PATH}${encodeURIComponent(agentId)}/improvement-report`, {
+    method: "GET",
+    headers: apiHeaders(ctx),
+  });
+  setCliAnalyticsContext(ctx, {
+    agent_id: res.agent_id,
+    trust_level: res.trust_level,
+    proposals_generated: res.proposals_generated,
+    proposals_applied: res.proposals_applied,
+    avg_score_delta_per_applied_change: res.avg_score_delta_per_applied_change,
+  });
+  queueCliAnalyticsEvent(ctx, "agent_improvement_report_viewed", {
+    agent_id: res.agent_id,
+    proposals_generated: res.proposals_generated,
+  });
+
+  if (ctx.jsonMode) {
+    printJson(ctx.stdout, res);
+  } else {
+    printSection(ctx.stdout, `Agent improvement report · ${res.agent_id}`);
+    printKeyValue(ctx.stdout, {
+      agent_id: res.agent_id,
+      trust_level: res.trust_level,
+      improvement_stalled_warning: res.improvement_stalled_warning,
+      proposals_generated: res.proposals_generated,
+      proposals_approved: res.proposals_approved,
+      proposals_vetoed: res.proposals_vetoed,
+      proposals_rejected: res.proposals_rejected,
+      proposals_applied: res.proposals_applied,
+      avg_score_delta_per_applied_change: res.avg_score_delta_per_applied_change,
+      current_tier: res.current_tier,
+      baseline_tier: res.baseline_tier,
+    });
+  }
+  return 0;
+}