@tpsdev-ai/flair 0.13.0 → 0.15.0

package/dist/cli-shim.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * cli-shim.cts — Node-version PREFLIGHT for the Flair CLI.
+ *
+ * THIS IS THE BIN ENTRY (`package.json` "bin": { "flair": "dist/cli-shim.cjs" }).
+ *
+ * Why a separate CommonJS file instead of a guard inside cli.ts:
+ *   The real CLI (dist/cli.js) is an ES module. In ESM, every top-level
+ *   `import` is HOISTED and the whole module graph is LINKED + EVALUATED before
+ *   the first statement in the file body runs. Flair's deps (harper-fabric-
+ *   embeddings requires Node >=22, @harperfast/harper / commander require >=20)
+ *   fail to load on an older engine — so a Node-version check placed even at the
+ *   very top of cli.ts never executes: the import graph crashes first. That is
+ *   exactly the silent-onboarding-failure bug (a Harper dev got zero output and
+ *   no ~/.flair on an old Node, fixed only by upgrading).
+ *
+ *   CommonJS evaluates top-to-bottom and `require()`/`import()` are evaluated
+ *   lazily — so the version check below runs and prints BEFORE anything tries to
+ *   load the ESM CLI or any modern dependency. Because every Node since v0.x
+ *   parses and runs CommonJS, this shim is guaranteed to run and print on the
+ *   oldest Node a developer could plausibly have.
+ *
+ *   The check itself deliberately uses ONLY ancient-safe syntax — `var`, plain
+ *   functions, string `.split`/`parseInt`, `console.error`, `process.exit`. No
+ *   top-level await, no optional chaining, no template literals reaching
+ *   modern-only APIs — so the guard can never become the thing that fails to
+ *   parse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+// ── Node-version preflight (must stay parse-safe + runtime-safe on old Node) ──
+var MIN_NODE_MAJOR = 22;
+function flairCurrentNodeMajor() {
+    // process.versions.node is e.g. "18.20.4"; take the leading integer.
+    var raw = (process && process.versions && process.versions.node) || "0";
+    return parseInt(String(raw).split(".")[0], 10) || 0;
+}
+var flairNodeMajor = flairCurrentNodeMajor();
+if (flairNodeMajor < MIN_NODE_MAJOR) {
+    // Plain string concatenation — no template literals, no chalk, nothing that
+    // could itself trip on an old engine.
+    console.error("");
+    console.error("  Flair requires Node.js >= " + MIN_NODE_MAJOR + ".");
+    console.error("  You are running Node.js " + (process.versions && process.versions.node ? process.versions.node : "(unknown)") + ".");
+    console.error("");
+    console.error("  Please upgrade Node and try again:");
+    console.error("    https://nodejs.org/  (or use nvm / fnm / volta)");
+    console.error("");
+    process.exit(1);
+}
+// Node is new enough — hand off to the real ESM CLI. Dynamic import() from
+// CommonJS is the supported ESM-from-CJS bridge. We only reach this line on a
+// supported Node, so the import() expression is never evaluated on an engine
+// that can't load the ESM graph.
+import("./cli.js")
+    .then(function (mod) {
+    if (mod && typeof mod.runCli === "function") {
+        return mod.runCli();
+    }
+    // Older builds auto-ran on import via import.meta.main; nothing to call.
+    return undefined;
+})
+    .catch(function (err) {
+    console.error(err && err.stack ? err.stack : err);
+    process.exit(1);
+});

package/dist/cli.js

@@ -11,6 +11,7 @@ import { createPrivateKey, sign as nodeCryptoSign, randomUUID, randomBytes } fro
 import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
 import { keystore } from "./keystore.js";
 import { deploy as deployToFabric, validateOptions as validateDeployOptions, buildTargetUrl as buildDeployUrl } from "./deploy.js";
+import { fabricUpgrade } from "./fabric-upgrade.js";
 import { detectClients, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
 // Federation crypto helpers — inlined to avoid cross-boundary imports from
 // src/ into resources/, which don't survive npm packaging (see also
@@ -491,11 +492,29 @@ export async function seedAgentViaOpsApi(opsPortOrUrl, agentId, pubKeyB64url, ad
     // Send Basic auth whenever the caller passed an adminPass. The caller decides
     // when to omit it (e.g., local target with authorizeLocal=true).
     const auth = adminPass !== undefined ? Buffer.from(`${adminUser}:${adminPass}`).toString("base64") : undefined;
+    // The ops-API insert bypasses the Agent resource layer, so Agent.post()'s
+    // 1.0 Principal defaults (kind/status/displayName/admin/defaultTrustTier/type)
+    // never run. Without them a remote-seeded agent lands kind=null, status=null
+    // and is invisible to roster/presence/Office-Space queries that filter on
+    // status='active' or kind='agent' (#521). Mirror Agent.post() exactly here.
+    const now = new Date().toISOString();
     const body = {
         operation: "insert",
         database: "flair",
         table: "Agent",
-        records: [{ id: agentId, name: agentId, publicKey: pubKeyB64url, createdAt: new Date().toISOString() }],
+        records: [{
+                id: agentId,
+                name: agentId,
+                type: "agent",
+                kind: "agent",
+                status: "active",
+                displayName: agentId,
+                admin: false,
+                defaultTrustTier: "unverified",
+                publicKey: pubKeyB64url,
+                createdAt: now,
+                updatedAt: now,
+            }],
     };
     const res = await fetch(url, {
         method: "POST",
@@ -2142,6 +2161,8 @@ agent
     .option("--admin-pass <pass>", "Admin password for registration")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--ops-port <port>", "Harper operations API port")
+    .option("--target <url>", "Remote Flair REST URL; derives the ops API URL (port-1) to seed the Agent there (env: FLAIR_TARGET)")
+    .option("--ops-target <url>", "Explicit ops API URL to seed the Agent on (env: FLAIR_OPS_TARGET; bypasses port derivation)")
     .action(async (id, opts) => {
     const httpPort = resolveHttpPort(opts);
     const opsPort = resolveOpsPort(opts);
@@ -2149,6 +2170,11 @@ agent
     const adminPass = opts.adminPass;
     const adminUser = DEFAULT_ADMIN_USER;
     const name = opts.name ?? id;
+    // Where to seed the Agent record. Default is localhost (opsPort). When
+    // --ops-target or --target is given, seed on the remote instead of localhost
+    // (#514 — agent add could only ever hit localhost ops). Precedence matches
+    // `flair import`: explicit --ops-target > derive from --target > localhost.
+    const seedOpsTarget = resolveEffectiveOpsUrl({ target: opts.target, opsTarget: opts.opsTarget }) ?? opsPort;
     if (!adminPass) {
         console.error("Error: --admin-pass is required for agent add (needed to insert into Agent table)");
         process.exit(1);
@@ -2172,8 +2198,10 @@ agent
         pubKeyB64url = b64url(kp.publicKey);
         console.log(`Keypair written: ${privPath}`);
     }
-    await seedAgentViaOpsApi(opsPort, id, pubKeyB64url, adminUser, adminPass);
-    console.log(`✅ Agent '${id}' (${name}) registered`);
+    await seedAgentViaOpsApi(seedOpsTarget, id, pubKeyB64url, adminUser, adminPass);
+    console.log(typeof seedOpsTarget === "string"
+        ? `✅ Agent '${id}' (${name}) registered (ops: ${seedOpsTarget})`
+        : `✅ Agent '${id}' (${name}) registered`);
     console.log(`   Private key: ${privPath}`);
     console.log(`   Public key:  ${pubKeyB64url}`);
 });
@@ -5766,14 +5794,104 @@ statusCmd
         console.log("\n✅ no warnings");
     }
 });
+// ─── flair upgrade --target <fabric> ────────────────────────────────────────
+//
+// One-command upgrade of a Flair instance DEPLOYED to a Harper Fabric cluster.
+// Mirrors `flair deploy`'s credential handling (FABRIC_USER/FABRIC_PASSWORD env
+// fallbacks, password-via-flag warning) and NEVER prints credentials. The
+// version-resolution + @harperfast/harper pin + reuse of deploy() lives in
+// src/fabric-upgrade.ts; this wrapper only does CLI plumbing + the confirm.
+async function runFabricUpgrade(opts) {
+    const green = (s) => `\x1b[32m${s}\x1b[0m`;
+    const red = (s) => `\x1b[31m${s}\x1b[0m`;
+    const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+    const fabricUser = opts.fabricUser ?? process.env.FABRIC_USER;
+    const fabricPassword = opts.fabricPassword ?? process.env.FABRIC_PASSWORD;
+    const check = opts.check ?? false;
+    // Creds are not required for --check (read-only registry + best-effort GET),
+    // but ARE required to actually deploy.
+    if (!check && !(fabricUser && fabricPassword)) {
+        console.error(red("flair upgrade --target: credentials required to deploy"));
+        console.error("  pass --fabric-user + --fabric-password (or FABRIC_USER / FABRIC_PASSWORD env)");
+        console.error("  or use --check to preview the plan without credentials");
+        process.exit(1);
+    }
+    // Warn on password-via-flag (leaks to shell history). Env is preferred.
+    if (opts.fabricPassword && !process.env.FABRIC_PASSWORD) {
+        console.error(dim("warning: --fabric-password leaks to shell history. Prefer FABRIC_PASSWORD env."));
+    }
+    const upgradeOpts = {
+        target: opts.target,
+        project: opts.project,
+        version: opts.version,
+        harperVersion: opts.harperVersion,
+        fabricUser,
+        fabricPassword,
+        check,
+        restart: opts.restart !== false,
+        replicated: opts.replicated !== false,
+    };
+    console.log(`${green("→")} Upgrading Fabric Flair at ${upgradeOpts.target}`);
+    if (check)
+        console.log(dim("  (--check: plan only, no deploy)"));
+    try {
+        // For a real (non-check) run, confirm first unless --yes. Building the plan
+        // up front would double the registry round-trips; the plan prints inside
+        // fabricUpgrade. We confirm BEFORE invoking when interactive and not --yes.
+        if (!check && !opts.yes && process.stdin.isTTY) {
+            const { createInterface } = await import("node:readline");
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const answer = await new Promise((res) => rl.question(`Deploy a fresh ${green("@tpsdev-ai/flair")} to ${upgradeOpts.target}? [y/N] `, (a) => { rl.close(); res(a); }));
+            if (!/^y(es)?$/i.test(answer.trim())) {
+                console.log("Aborted.");
+                return;
+            }
+        }
+        const result = await fabricUpgrade(upgradeOpts);
+        if (check) {
+            console.log(`\n${green("✓")} check complete — run without --check to deploy.`);
+            return;
+        }
+        if (result.plan.upToDate && !result.deployed) {
+            console.log(`\n${green("✓")} already up to date.`);
+            return;
+        }
+        console.log(`\n${green("✓")} Fabric upgrade complete.`);
+    }
+    catch (err) {
+        console.error(red(`\n✗ fabric upgrade failed: ${err.message}`));
+        const hint = err.message?.toLowerCase() ?? "";
+        if (hint.includes("401") || hint.includes("unauthoriz")) {
+            console.error(dim("  hint: check Fabric Studio → Cluster Settings → Admin for the admin password"));
+        }
+        process.exit(1);
+    }
+}
 // ─── flair upgrade ────────────────────────────────────────────────────────────
 program
     .command("upgrade")
-    .description("Upgrade Flair and related packages to latest versions")
-    .option("--check", "Only check for updates, don't install")
+    .description("Upgrade Flair — local packages by default, or a deployed Fabric with --target")
+    .option("--check", "Only check for updates / show the plan, don't install or deploy")
     .option("--restart", "Restart Flair after upgrade")
     .option("--all", "Show transitive packages (e.g. flair-client) in the listing — verbose mode for debugging dep versions")
+    // ── Fabric upgrade (--target) ────────────────────────────────────────────
+    // When --target is passed, upgrade the Flair component DEPLOYED to that
+    // Harper Fabric URL instead of the local npm install. Reuses `flair deploy`
+    // under the hood with the @harperfast/harper pin baked in (flair#513).
+    .option("--target <url>", "Upgrade the Flair deployed to this Fabric URL (not the local install)")
+    .option("--fabric-user <user>", "Fabric admin username (env: FABRIC_USER) — for --target")
+    .option("--fabric-password <pass>", "Fabric admin password (env: FABRIC_PASSWORD) — for --target")
+    .option("--version <semver>", "Flair version to deploy with --target (default: latest published @tpsdev-ai/flair)")
+    .option("--harper-version <semver>", "Pin @harperfast/harper to this version for --target (default: registry latest, floored at the flair#513 fix)")
+    .option("--project <name>", "Fabric component name for --target", "flair")
+    .option("--no-replicated", "Disable cluster-wide replication for --target (default: replicated=true)")
+    .option("--yes", "Skip the confirmation prompt for --target")
     .action(async (opts) => {
+    // ── Fabric-upgrade branch ───────────────────────────────────────────────
+    if (opts.target) {
+        await runFabricUpgrade(opts);
+        return;
+    }
     const { execSync, execFileSync } = await import("node:child_process");
     const checkOnly = opts.check ?? false;
     const showAll = opts.all ?? false;
@@ -7005,6 +7123,7 @@ memory.command("add [content]").requiredOption("--agent <id>")
     .option("--summary <text>", "agent-set multi-sentence dense compression (3-tier chain: subject → summary → content; ops-wkoh)")
     .option("--subject <text>", "one-line title / entity this memory is about")
     .option("--derived-from <csv>", "Comma-separated source Memory IDs this memory was distilled/reflected from (sets Memory.derivedFrom; used by the `rem rapid` reflection loop)")
+    .option("--visibility <value>", "Memory visibility (sets Memory.visibility). Use 'office' to share office-wide with every team agent; omit (default) to keep it private to this agent (flair#509)")
     .action(async (contentArg, opts) => {
     const content = contentArg ?? opts.content;
     if (!content) {
@@ -7021,6 +7140,8 @@ memory.command("add [content]").requiredOption("--agent <id>")
         body.summary = opts.summary;
     if (opts.subject)
         body.subject = opts.subject;
+    if (opts.visibility)
+        body.visibility = String(opts.visibility).trim();
     if (opts.derivedFrom) {
         body.derivedFrom = String(opts.derivedFrom).split(",").map((x) => x.trim()).filter(Boolean);
     }
@@ -8654,11 +8775,20 @@ program
     .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--url <url>", "Flair base URL (overrides --port)")
+    .option("--ops-target <url>", "Explicit ops API URL for the Agent seed (env: FLAIR_OPS_TARGET; bypasses port derivation). Use when --url is remote and the ops port isn't HTTP-1.")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .option("--keys-dir <dir>", "Keys directory", defaultKeysDir())
     .action(async (importPath, opts) => {
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
     const opsPort = resolveOpsPort(opts);
+    // Resolve where the Agent record is seeded. The Agent goes through the ops
+    // API (the REST surface has no Agent POST handler), so a remote --url import
+    // must NOT silently seed on localhost (#514 — split import). Precedence:
+    //   1. --ops-target / FLAIR_OPS_TARGET → use directly
+    //   2. --url given → derive ops URL from it (port-1 convention)
+    //   3. neither → localhost opsPort (preserves local default)
+    // The remote REST base (--url) is mapped to `target` for derivation.
+    const seedOpsTarget = resolveEffectiveOpsUrl({ target: opts.url, opsTarget: opts.opsTarget }) ?? opsPort;
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
     if (!adminPass) {
         console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required");
@@ -8706,9 +8836,11 @@ program
         ? nacl.sign.keyPair.fromSeed(new Uint8Array(decodedSeed)).publicKey
         : nacl.sign.keyPair.fromSeed(new Uint8Array(decodedSeed.subarray(0, 32))).publicKey;
     const pubKeyB64url = b64url(pubKey);
-    // Register agent via ops API
-    await seedAgentViaOpsApi(opsPort, agentId, pubKeyB64url, DEFAULT_ADMIN_USER, adminPass);
-    console.log(`  Agent registered`);
+    // Register agent via ops API (remote when --url/--ops-target points off-box)
+    await seedAgentViaOpsApi(seedOpsTarget, agentId, pubKeyB64url, DEFAULT_ADMIN_USER, adminPass);
+    console.log(typeof seedOpsTarget === "string"
+        ? `  Agent registered (ops: ${seedOpsTarget})`
+        : `  Agent registered`);
     // Restore memories
     const auth = `Basic ${Buffer.from(`${DEFAULT_ADMIN_USER}:${adminPass}`).toString("base64")}`;
     let memCount = 0;
@@ -9102,9 +9234,159 @@ presence
         console.log(`  Status: ${data.presenceStatus}`);
     }
 });
-// Run CLI only when this is the entry point (not when imported for testing)
-if (import.meta.main) {
+// ─── flair workspace ─────────────────────────────────────────────────────────
+//
+// Coordination write surface (ops-wmgx / Kris #510). `workspace set` writes the
+// agent's OWN WorkspaceState via a signed POST /WorkspaceState. Identity comes
+// from the Ed25519 signature — the body carries NO agentId, so an agent can only
+// write as itself (the WorkspaceState.post() handler overwrites agentId from the
+// signature regardless of body content). Mirrors `presence set`'s signed-POST shape.
+const MAX_WORKSPACE_FIELD_LENGTH = 2000;
+const workspace = program.command("workspace").description("Manage agent workspace state (The Office Space)");
+workspace
+    .command("set")
+    .description("Set your agent's current workspace state (POST /WorkspaceState)")
+    .requiredOption("--ref <ref>", "Workspace ref (branch, worktree, or task ref)")
+    .option("--label <text>", "Human-readable label for this workspace")
+    .option("--provider <name>", "Provider/runtime (e.g. claude-code, openclaw)", "cli")
+    .option("--task <id>", "Task/issue id this workspace is attached to")
+    .option("--phase <phase>", "Current phase (e.g. design, implement, review)")
+    .option("--summary <text>", "Short summary of current workspace state")
+    .option("--agent <id>", "Agent ID (env: FLAIR_AGENT_ID)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .action(async (opts) => {
+    const agentId = resolveAgentIdOrEnv(opts);
+    if (!agentId) {
+        console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
+        process.exit(1);
+    }
+    // Validate field lengths (free text → cap to bound the write).
+    for (const [name, val] of [["ref", opts.ref], ["label", opts.label], ["summary", opts.summary]]) {
+        if (val && String(val).length > MAX_WORKSPACE_FIELD_LENGTH) {
+            console.error(`Error: --${name} exceeds ${MAX_WORKSPACE_FIELD_LENGTH} character limit (got ${String(val).length}).`);
+            process.exit(1);
+        }
+    }
+    const keyPath = resolveKeyPath(agentId);
+    if (!keyPath) {
+        console.error(`Error: private key not found for agent '${agentId}'. Check ~/.flair/keys/ or set FLAIR_KEY_DIR.`);
+        process.exit(1);
+    }
+    const baseUrl = resolveBaseUrl(opts).replace(/\/$/, "");
+    const auth = buildEd25519Auth(agentId, "POST", "/WorkspaceState", keyPath);
+    // NOTE: agentId is intentionally NOT included in the body — the handler
+    // attributes the record from the Ed25519 signature (no forging).
+    const now = new Date().toISOString();
+    const body = {
+        id: `${agentId}:${opts.ref}`,
+        ref: opts.ref,
+        provider: opts.provider ?? "cli",
+        timestamp: now,
+    };
+    if (opts.label)
+        body.label = opts.label;
+    if (opts.task)
+        body.taskId = opts.task;
+    if (opts.phase)
+        body.phase = opts.phase;
+    if (opts.summary)
+        body.summary = opts.summary;
+    const res = await fetch(`${baseUrl}/WorkspaceState`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: POST /WorkspaceState failed (${res.status}): ${text}`);
+        process.exit(1);
+    }
+    console.log(`✓ Workspace state updated for '${agentId}': ref=${opts.ref}${opts.phase ? `, phase=${opts.phase}` : ""}`);
+});
+// ─── flair orgevent ──────────────────────────────────────────────────────────
+//
+// Coordination write surface (ops-wmgx / Kris #510). `orgevent` publishes an
+// OrgEvent ATTRIBUTED to the authenticated agent via a signed POST /OrgEvent.
+// The event's authorId comes from the Ed25519 signature — the body carries NO
+// authorId, so an agent CANNOT forge another agent's events (the OrgEvent.post()
+// handler overwrites authorId from the signature). Mirrors `presence set`'s shape.
+const MAX_ORGEVENT_SUMMARY_LENGTH = 500;
+const MAX_ORGEVENT_DETAIL_LENGTH = 8000;
+program
+    .command("orgevent")
+    .description("Publish an org-wide coordination event attributed to your agent (POST /OrgEvent)")
+    .requiredOption("--kind <kind>", "Event kind (e.g. coord.claim, coord.release, status)")
+    .requiredOption("--summary <text>", "Short summary of the event")
+    .option("--detail <text>", "Longer detail payload")
+    .option("--scope <scope>", "Scope of the event (e.g. an agent id, repo, or 'org')")
+    .option("--target <agentId>", "Recipient agent id (repeatable)", (val, acc) => { acc.push(val); return acc; }, [])
+    .option("--agent <id>", "Agent ID (env: FLAIR_AGENT_ID)")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--target-url <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    .action(async (opts) => {
+    const agentId = resolveAgentIdOrEnv(opts);
+    if (!agentId) {
+        console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
+        process.exit(1);
+    }
+    if (opts.summary && String(opts.summary).length > MAX_ORGEVENT_SUMMARY_LENGTH) {
+        console.error(`Error: --summary exceeds ${MAX_ORGEVENT_SUMMARY_LENGTH} character limit (got ${String(opts.summary).length}).`);
+        process.exit(1);
+    }
+    if (opts.detail && String(opts.detail).length > MAX_ORGEVENT_DETAIL_LENGTH) {
+        console.error(`Error: --detail exceeds ${MAX_ORGEVENT_DETAIL_LENGTH} character limit (got ${String(opts.detail).length}).`);
+        process.exit(1);
+    }
+    const keyPath = resolveKeyPath(agentId);
+    if (!keyPath) {
+        console.error(`Error: private key not found for agent '${agentId}'. Check ~/.flair/keys/ or set FLAIR_KEY_DIR.`);
+        process.exit(1);
+    }
+    // orgevent reuses --target for recipients, so the remote-URL override is
+    // --target-url here (env FLAIR_TARGET still honored via resolveBaseUrl).
+    const baseUrl = resolveBaseUrl({ target: opts.targetUrl, port: opts.port }).replace(/\/$/, "");
+    const auth = buildEd25519Auth(agentId, "POST", "/OrgEvent", keyPath);
+    // NOTE: authorId is intentionally NOT included in the body — the handler
+    // attributes the event from the Ed25519 signature (no forging).
+    const body = {
+        kind: opts.kind,
+        summary: opts.summary,
+    };
+    if (opts.detail)
+        body.detail = opts.detail;
+    if (opts.scope)
+        body.scope = opts.scope;
+    if (Array.isArray(opts.target) && opts.target.length > 0)
+        body.targetIds = opts.target;
+    const res = await fetch(`${baseUrl}/OrgEvent`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(`Error: POST /OrgEvent failed (${res.status}): ${text}`);
+        process.exit(1);
+    }
+    const data = await res.json().catch(() => null);
+    const targets = Array.isArray(opts.target) && opts.target.length > 0 ? ` → ${opts.target.join(", ")}` : "";
+    console.log(`✓ OrgEvent published as '${agentId}': kind=${opts.kind}${targets}`);
+    if (data?.id)
+        console.log(`  id: ${data.id}`);
+});
+// Parse argv and run the CLI. Exported so the CommonJS preflight shim
+// (cli-shim.cts → dist/cli-shim.cjs, the real bin entry) can invoke it after
+// its Node-version check passes. The shim imports this module, so import.meta.main
+// is false there — without this explicit entry point the CLI would load but never run.
+async function runCli() {
     await program.parseAsync();
 }
+// Run CLI directly when this file is the entry point — covers `node dist/cli.js`,
+// `bun src/cli.ts`, and the test harness (which spawns src/cli.ts under bun).
+// The packaged bin goes through cli-shim.cjs → runCli() instead.
+if (import.meta.main) {
+    await runCli();
+}
 // ─── Exported for testing ─────────────────────────────────────────────────────
-export { resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, };
+export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, resolveHttpPort, resolveOpsPort, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, };