@askexenow/exe-os 0.9.127 → 0.9.129

package/dist/chunk-6M5II4EV.js

@@ -0,0 +1,148 @@
+import {
+  getClient,
+  init_database,
+  isInitialized
+} from "./chunk-A2NZP64U.js";
+import {
+  EMPLOYEES_PATH,
+  init_employees,
+  loadEmployees
+} from "./chunk-RUG3N6P4.js";
+import {
+  PLAN_LIMITS,
+  checkLicense,
+  init_license,
+  isFeatureAllowed
+} from "./chunk-IRQTM7DY.js";
+import {
+  EXE_AI_DIR,
+  init_config
+} from "./chunk-KVPG5UT6.js";
+import {
+  __esm
+} from "./chunk-KFQGP6VL.js";
+
+// src/lib/plan-limits.ts
+import { readFileSync, existsSync } from "fs";
+import path from "path";
+function getLicenseSync() {
+  try {
+    if (!existsSync(CACHE_PATH)) return freeLicense();
+    const raw = JSON.parse(readFileSync(CACHE_PATH, "utf8"));
+    if (!raw.token || typeof raw.token !== "string") return freeLicense();
+    const parts = raw.token.split(".");
+    if (parts.length !== 3) return freeLicense();
+    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString());
+    const plan = payload.plan ?? "free";
+    const limits = PLAN_LIMITS[plan] ?? PLAN_LIMITS.free;
+    return {
+      valid: true,
+      plan,
+      email: payload.sub ?? "",
+      expiresAt: payload.exp ? new Date(payload.exp * 1e3).toISOString() : null,
+      deviceLimit: limits.devices,
+      employeeLimit: limits.employees,
+      memoryLimit: limits.memories
+    };
+  } catch {
+    return freeLicense();
+  }
+}
+function freeLicense() {
+  const limits = PLAN_LIMITS.free;
+  return {
+    valid: true,
+    plan: "free",
+    email: "",
+    expiresAt: null,
+    deviceLimit: limits.devices,
+    employeeLimit: limits.employees,
+    memoryLimit: limits.memories
+  };
+}
+async function countActiveMemories() {
+  if (!isInitialized()) return 0;
+  const client = getClient();
+  const result = await client.execute(
+    "SELECT COUNT(*) as cnt FROM memories WHERE status = 'active' OR status IS NULL"
+  );
+  const row = result.rows[0];
+  return Number(row?.cnt ?? 0);
+}
+async function assertMemoryLimit() {
+  const license = await checkLicense();
+  if (license.memoryLimit < 0) return;
+  const count = await countActiveMemories();
+  if (count >= license.memoryLimit) {
+    throw new PlanLimitError(
+      `Memory limit reached: ${count}/${license.memoryLimit} active memories on the ${license.plan} plan. Upgrade at https://askexe.com to store more.`
+    );
+  }
+}
+async function assertEmployeeLimit(license, rosterPath) {
+  const lic = license ?? await checkLicense();
+  if (lic.employeeLimit < 0) return;
+  const employees = await loadEmployees(rosterPath ?? EMPLOYEES_PATH);
+  if (employees.length >= lic.employeeLimit) {
+    throw new PlanLimitError(
+      `Employee limit reached: ${employees.length}/${lic.employeeLimit} employees on the ${lic.plan} plan. Upgrade at https://askexe.com to add more.`
+    );
+  }
+}
+function assertEmployeeLimitSync(rosterPath) {
+  const license = getLicenseSync();
+  if (license.employeeLimit < 0) return;
+  const filePath = rosterPath ?? EMPLOYEES_PATH;
+  let count = 0;
+  try {
+    if (existsSync(filePath)) {
+      const raw = readFileSync(filePath, "utf8");
+      const employees = JSON.parse(raw);
+      count = Array.isArray(employees) ? employees.length : 0;
+    }
+  } catch {
+    throw new PlanLimitError(
+      `Cannot verify employee count: roster unreadable at ${filePath}. Refusing to proceed. Check file permissions or upgrade plan.`
+    );
+  }
+  if (count >= license.employeeLimit) {
+    throw new PlanLimitError(
+      `Employee limit reached: ${count}/${license.employeeLimit} employees on the ${license.plan} plan. Upgrade at https://askexe.com to add more.`
+    );
+  }
+}
+async function assertFeature(feature) {
+  const license = await checkLicense();
+  if (!isFeatureAllowed(license, feature)) {
+    throw new PlanLimitError(
+      `Feature "${feature}" requires a paid plan. Current plan: ${license.plan}. Upgrade at https://askexe.com.`
+    );
+  }
+}
+var PlanLimitError, CACHE_PATH;
+var init_plan_limits = __esm({
+  "src/lib/plan-limits.ts"() {
+    init_database();
+    init_employees();
+    init_license();
+    init_config();
+    PlanLimitError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "PlanLimitError";
+      }
+    };
+    CACHE_PATH = path.join(EXE_AI_DIR, "license-cache.json");
+  }
+});
+
+export {
+  PlanLimitError,
+  getLicenseSync,
+  countActiveMemories,
+  assertMemoryLimit,
+  assertEmployeeLimit,
+  assertEmployeeLimitSync,
+  assertFeature,
+  init_plan_limits
+};

package/dist/chunk-6QEFN3DV.js

@@ -0,0 +1,302 @@
+// src/lib/platform-procedures.ts
+var PLATFORM_PROCEDURES = [
+  // --- Foundation: what is exe-os ---
+  {
+    title: "What is exe-os \u2014 the operating model every agent must understand",
+    domain: "architecture",
+    priority: "p0",
+    content: "Exe OS is an AI employee operating system. A founder runs 5-10 AI agents as a real org: COO, CTO, CMO, engineers, and content production specialists. Each agent has identity, expertise, and experience layers \u2014 persistent memory that makes them better over time. All data is local-first, E2EE, owned by the user. The MCP server is the ONLY data interface \u2014 never access the DB directly."
+  },
+  {
+    title: "Mode 1 \u2014 how exe-os runs inside Claude Code",
+    domain: "architecture",
+    priority: "p0",
+    content: "Mode 1: exe-os runs AS hooks + MCP + skills inside Claude Code, Codex, or OpenCode. The founder picks their default tool at setup. The COO manages employees in tmux sessions. Each coordinator session is a separate window/project. Employees run in their own tmux panes via create_task auto-spawn. The founder talks to the COO; the COO orchestrates the team. The tool is the shell, exe-os is the brain."
+  },
+  {
+    title: "Sessions explained \u2014 coordinator session names and projects",
+    domain: "architecture",
+    priority: "p0",
+    content: "Each coordinator session is an isolated project session. One might be exe-os development, another might be exe-wiki. Each session spawns its own employees using {employee}-{coordinatorSession}. Sessions share the same memory DB but tasks are scoped to the session that created them. A founder can run multiple projects simultaneously. Sessions never interfere with each other."
+  },
+  {
+    title: "Runtime settings \u2014 COO can view and change tools per agent",
+    domain: "workflow",
+    priority: "p1",
+    content: "exe-os supports three tools: Claude Code (Anthropic), Codex (OpenAI), and OpenCode (open source, 75+ providers). Each agent can use a different tool and model. COO uses set_agent_config MCP tool to view or change settings. Call with no args to show all agents. Call with agent_id + runtime + model to change. Users can also run `exe-os settings` from terminal for interactive arrow-key selection."
+  },
+  // --- Updates and deployment ---
+  {
+    title: "How to update exe-os \u2014 CLI update + stack update (two steps)",
+    domain: "operations",
+    priority: "p0",
+    content: 'Updating exe-os is a two-step process. Step 1 \u2014 update the CLI: `npm install -g @askexenow/exe-os@latest` (gets bug fixes, new platform procedures, new tools). Step 2 \u2014 update the VPS stack (if applicable): `exe-os stack-update --target <version> --yes` (pulls new Docker images for exed, wiki, CRM, gateway). Step 1 MUST happen before Step 2 \u2014 the stack-update command itself may have bug fixes. After updating, restart the daemon: the deploy script handles this automatically. Check update availability: `exe-os update --check` or config(action="check_update"). Agents should NEVER run npm install or stack-update autonomously \u2014 always confirm with the user first.'
+  },
+  {
+    title: "First install \u2014 setup wizard and license activation",
+    domain: "operations",
+    priority: "p1",
+    content: "Fresh install: `npm install -g @askexenow/exe-os` then run `exe` to start the setup wizard. The wizard prompts for: encryption passphrase (creates master key), license key (exe_sk_* from AskExe team), COO name, and optional team members. No license key = free tier (1 employee, 5K memories). After setup: hooks install automatically, MCP server registers in ~/.claude.json, daemon starts. Verify health: run `exe-os healthcheck` or use mcp_ping() tool."
+  },
+  // --- Hierarchy and dispatch ---
+  {
+    title: "Chain of command \u2014 who talks to whom",
+    domain: "workflow",
+    priority: "p0",
+    content: "Founder -> coordinator (the executive agent, internally routed as 'COO') -> CTO/CMO. CTO -> engineers. CMO -> content production. Never skip levels: the coordinator does not bypass managers for specialist work. Specialists report to their manager. If you need cross-team info, use ask_team_memory \u2014 don't read other agents' task folders. Each level owns dispatch downward and review upward."
+  },
+  {
+    title: "Orchestration phase guidance \u2014 recommend, never trap",
+    domain: "workflow",
+    priority: "p1",
+    content: "New customers start best in Phase 1: founder \u2194 coordinator/Chief of Staff, building company context. Suggest Phase 2 executives when domain work repeats; suggest Phase 3 parallel execution only when review/permission gates are ready. This is guidance, not a blocker: users may jump phases anytime. Never overwrite their phase, role titles, identities, or custom org design."
+  },
+  {
+    title: "Routing slot vs display title \u2014 internal 'coo' is plumbing, not your name",
+    domain: "identity",
+    priority: "p0",
+    content: "These procedures reference 'COO' as a shorthand for the coordinator role. This is an INTERNAL routing slot used by exe-os code (chain-of-command checks, dispatch logic, session detection). It is NOT your display title. Your actual title comes from your identity file's `title:` field \u2014 that is what you use externally: introductions, sign-offs, team comms, and any user-facing text. If your identity says `title: AI Chief of Staff`, you are the AI Chief of Staff. The internal routing slot stays unchanged for code compatibility \u2014 never rename it, but also never introduce yourself as 'COO' unless your identity file explicitly says so. The founder chose your title; respect it."
+  },
+  {
+    title: "Single dispatch path \u2014 create_task only",
+    domain: "workflow",
+    priority: "p0",
+    content: "create_task is the ONLY way to dispatch work to another agent. No direct ensureEmployee calls, no manual tmux spawns, no send_message for actionable work. create_task \u2192 system auto-spawns \u2192 session correctly named. ONE PATH. No backdoors. No exceptions."
+  },
+  // --- Session isolation ---
+  {
+    title: "Session scoping \u2014 stay in your coordinator boundary",
+    domain: "security",
+    priority: "p0",
+    content: "Session scoping is mandatory. Managers dispatch to workers within their own coordinator session ONLY. Employee sessions use {employee}-{coordinatorSession}. Cross-session dispatch is blocked by the system. Verify session names before dispatch. Tasks are scoped to the creating coordinator session."
+  },
+  {
+    title: "Session isolation \u2014 never touch another session's work",
+    domain: "workflow",
+    priority: "p0",
+    content: "Sessions are isolated. A coordinator session owns ONLY tasks it dispatched. (1) Never close/update/cancel tasks from another coordinator session. (2) Never review work from a different session \u2014 report that it belongs to another session and skip. (3) Ignore other sessions' items in list_tasks results. (4) Employees inherit session: employee sessions work ONLY on their parent coordinator session's tasks. Cross-session work is a system violation."
+  },
+  // --- Engineering: session scoping in code ---
+  {
+    title: "Three-dimensional scoping \u2014 session, project, role \u2014 enforced in every query",
+    domain: "architecture",
+    priority: "p0",
+    content: "Every DB query, notification, review count, and task operation MUST be scoped on 3 dimensions: (1) Session \u2014 filter by session_scope matching the current coordinator session. (2) Project \u2014 filter by project_name. (3) Role \u2014 agents only see data at their hierarchy level. When writing ANY function that touches tasks, reviews, messages, or notifications: always accept a sessionScope parameter and pass it to the SQL WHERE clause. Unscoped queries are bugs. Test by running 2+ coordinator sessions simultaneously."
+  },
+  // --- Hard constraints ---
+  {
+    title: "What you CANNOT do in exe-os \u2014 hard constraints",
+    domain: "security",
+    priority: "p0",
+    content: "NEVER: (1) Access the database directly \u2014 it's SQLCipher encrypted, always fails. Use MCP tools only. (2) Manually spawn tmux sessions \u2014 create_task handles it. (3) Run git checkout main \u2014 agents work in worktrees. (4) Modify another agent's in-progress task. (5) Push to remote \u2014 the COO reviews and pushes. (6) Skip update_task(done) \u2014 it's the ONLY way your work gets reviewed. (7) Run git init."
+  },
+  {
+    title: "Destructive operations \u2014 mandatory reviewer gate",
+    domain: "security",
+    priority: "p0",
+    content: "Before ANY destructive operation (delete, remove, overwrite, drop, reset, force-push, truncate), you MUST: (1) Have your full task spec accessible \u2014 if you cannot read it, STOP and report to your reviewer. Never improvise destructive actions. (2) Confirm with your reviewer (assigned_by or COO) before executing. (3) If the task spec explicitly authorizes the operation, proceed \u2014 but log it. Violation = immediate task failure. This applies to ALL agents regardless of role."
+  },
+  {
+    title: "Customer patch triage \u2014 upstream bug vs customization",
+    domain: "support",
+    priority: "p0",
+    content: "When an agent encounters a suspected Exe OS bug, update breakage, MCP/tool failure, installer issue, memory/orchestration defect, or customer-local patch need, it MUST use create_bug_report. Do this before or alongside any local workaround so the report reaches AskExe support directly via the customer's license. Do NOT ask the founder for permission to file a required bug report. If create_bug_report is deferred/lazy-loaded, load it and call it. If it is unavailable in the live MCP surface, report 'create_bug_report unavailable in this session' and save a local report in exe/output \u2014 never claim the tool does not exist unless the live MCP surface was checked. If upstream delivery fails, call support_test (MCP) and include its result in the local report so AskExe can distinguish customer setup, license provisioning, and server intake issues; only ask the founder to run `exe-os support test` if MCP is disconnected/unavailable. Classify first: upstream_bug = reproducible exe-os/platform defect; customer_customization = identity, behavior, procedure, config, branding, workflow preference that belongs in customer-owned layers; emergency_hotfix = temporary local patch. For upstream bugs/emergency hotfixes include version, repro steps, expected/actual, files changed, workaround, and local diff summary. Avoid permanent platform-code patches unless founder approves; if a hotfix is unavoidable, document it in the bug report and re-check after npm update."
+  },
+  {
+    title: "Bug report status check \u2014 surface available fixes on boot",
+    domain: "support",
+    priority: "p1",
+    content: "Once per session (COO boot only, never repeat), call support(action='list_my_bugs') to check if any previously filed bug reports have been fixed by AskExe. If any report has status 'closed' with a fixed_version, surface it to the founder immediately: '\u{1F527} N bug fix(es) available \u2014 run exe-os update to get version X.Y.Z'. You can also file new bugs with support(action='create_bug') and check status anytime with support(action='list_my_bugs'). This boot check is one-time, not a recurring poll. If the tool is unavailable, skip silently."
+  },
+  {
+    title: "Feature request triage \u2014 upstream feature vs local customization",
+    domain: "support",
+    priority: "p0",
+    content: "When an agent or founder identifies a desired capability that exe-os does not yet provide, the COO (or equivalent coordinator) must decide: is this a local customization (identity, behavior, procedure, config, branding, workflow preference that can be configured in customer-owned layers) or an upstream feature request (a platform capability that requires changes to exe-os code, shipped via npm update)? Local customizations: implement immediately using store_behavior, update_identity, company_procedure, or config changes. Upstream features: use create_feature_request to submit to AskExe. Include use case, business impact, and current workaround. Do NOT ask the founder for permission to file a feature request \u2014 file it proactively when the need is clear."
+  },
+  {
+    title: "Feature request status check \u2014 surface shipped features on boot",
+    domain: "support",
+    priority: "p1",
+    content: "Once per session (COO boot only, never repeat), call support(action='list_my_features') to check if any previously filed feature requests have been shipped by AskExe. If any request has status 'shipped' with a shipped_version, surface it to the founder immediately: '\u{1F680} N feature(s) shipped \u2014 run exe-os update to get version X.Y.Z'. You can also file new requests with support(action='create_feature') and check status anytime with support(action='list_my_features'). This boot check is one-time, not a recurring poll. If the tool is unavailable, skip silently."
+  },
+  // --- Tool guidance ---
+  {
+    title: "How to use company_actions \u2014 execute business actions through gateway connectors",
+    domain: "tools",
+    priority: "p2",
+    content: "The company_actions tool executes business actions through gateway connectors (e.g. send WhatsApp, trigger workflows, update CRM). It routes through the exe-gateway on the VPS. Actions are defined by the customer's gateway configuration \u2014 each connector (WhatsApp, Shopify, email, etc.) exposes specific actions. Use query_company_brain to find available data first, then company_actions to act on it. Requires gateway auth token. Read-only founders should NOT use this \u2014 it mutates external state."
+  },
+  // --- Release awareness ---
+  {
+    title: "What's New check \u2014 surface new features after update",
+    domain: "support",
+    priority: "p1",
+    content: "Once per session (COO boot only, never repeat), check if the installed exe-os version is newer than the last session. If it is, read the bundled release-notes.json (at the package root) and surface a brief summary to the founder: 'Updated to exe-os vX.Y.Z \u2014 N new features, M fixes.' List the top 3 features by name. This helps the founder know what they got from the update. If release-notes.json doesn't exist or the version hasn't changed, skip silently. Never repeat this check in the same session."
+  },
+  // --- Platform vs Customer ownership ---
+  {
+    title: "What the platform provides vs what you customize",
+    domain: "architecture",
+    priority: "p0",
+    content: "Exe OS has two layers. PLATFORM layer (shipped in code, updated via npm): platform procedures, default identity templates, MCP tools, tool gating, schema migrations, daemon behavior. You get improvements automatically on update. CUSTOMER layer (yours, stored locally): agent identities (exe.md files), behaviors, company procedures, config.json, wiki content, CRM data, memory. These are NEVER overwritten by updates. Identity templates are stamped once at /exe-new-employee \u2014 after that the file is yours. If the platform ships a better template, you can compare yours against the default with getTemplate() and merge what you want. Company procedures (company_procedure tool) layer ON TOP of platform procedures \u2014 both are injected, platform first. FIVE LAYERS \u2014 know when to use each: (1) Platform procedures: how exe-os works, shipped to ALL customers, updated via npm. Never put org-specific rules here. (2) Company procedures: your org's workflow rules, stored in DB, injected after platform. Use for internal gates, review checklists, org-specific policies. (3) Identity (exe.md): an agent's permanent role definition \u2014 who they are, what they own, non-negotiable rules. Use for rules that must NEVER be forgotten across sessions. (4) Behaviors: corrections and learned patterns (Layer 2 expertise). Use for 'from now on do X' or 'never do Y again' \u2014 scoped per agent per project, deactivatable. (5) Memory: facts, decisions, context (Layer 3 experience). Use for what happened, what was decided, project state. Searchable, consolidatable. Rule of thumb: platform procedures for product behavior, company procedures for org workflow, identity for permanent role rules, behaviors for per-agent per-project corrections, memory for facts. Behaviors are always yours. Config is always yours. The platform will never modify your local data."
+  },
+  // --- Updates ---
+  {
+    title: "How to update exe-os \u2014 CLI first, then stack",
+    domain: "operations",
+    priority: "p0",
+    content: "When bug fixes or features are available (surfaced at boot via list_my_bug_reports/list_my_feature_requests), update in two steps: (1) CLI: `npm install -g @askexenow/exe-os@latest` \u2014 this updates the local tools, MCP server, and bundled stack manifest. Must happen first so the stack-update tool itself has the latest fixes. (2) Stack (VPS only): `exe-os stack-update --target <version> --yes` \u2014 pulls new Docker images and restarts services. The target version comes from the stack manifest bundled with the CLI. Always update CLI before stack. Use `exe-os update --check` to see if a CLI update is available. Use `exe-os stack-update --check` to see stack status. For non-interactive/SSH: use `--yes` or `-y` flag. Never run `npm install -g` inside a tmux agent session \u2014 have the founder or COO do it from the host shell. If stack-update fails with EACCES on /opt/exe-stack, run: `sudo mkdir -p /opt/exe-stack && sudo chown $(whoami) /opt/exe-stack` then retry."
+  },
+  {
+    title: "CLI version vs stack version \u2014 two tracks, both normal",
+    domain: "operations",
+    priority: "p0",
+    content: "exe-os has TWO version numbers that move independently. This is normal \u2014 do not treat a mismatch as an error. (1) CLI version (e.g. 0.9.89, 0.9.90) \u2014 the npm package installed locally. Updates frequently: bug fixes, new MCP tools, platform procedures, search improvements, client-side changes. Update with `npm install -g @askexenow/exe-os@latest`. (2) Stack version (e.g. 0.9.7, 0.9.8) \u2014 the Docker images on the VPS. Updates less frequently: only when server-side daemon, gateway, wiki, or CRM images need rebuilding. Update with `exe-os stack-update --target <version> --yes`. The CLI version will almost always be higher than the stack version. A CLI at 0.9.90 with a stack at 0.9.8 is perfectly normal \u2014 it means the CLI got 12 patches since the last Docker image rebuild. Only update the stack when: (a) the boot brief surfaces a fix that mentions 'stack update required', (b) a new stack manifest version is bundled in the CLI (`exe-os stack-update --check` shows pending changes), or (c) AskExe support explicitly tells you to. Do NOT attempt to make the numbers match \u2014 they are separate tracks."
+  },
+  {
+    title: "Update lifecycle \u2014 what each command does and what picks up new code",
+    domain: "operations",
+    priority: "p0",
+    content: "Three update paths exist \u2014 know which does what. (1) `npm install -g @askexenow/exe-os@latest` \u2014 customer update. Replaces all dist/ files. postinstall copies slash commands AND restarts the daemon automatically. MCP server picks up new code on next `/mcp` reconnect or new Claude Code session. Hooks pick up new code on next session (they spawn fresh processes). (2) `exe-os update` \u2014 interactive update command. Runs `npm install -g` then `install --global` which restarts daemon, regenerates session wrappers, normalizes roster, registers Codex hooks. This is the recommended customer path. (3) `npm run deploy` \u2014 dev-only (COO/CTO on main branch). Builds, installs globally, runs `install --global`, restarts daemon. Never run from a worktree. NEVER confuse `exe-os setup` (first-time setup wizard for new installs) with `exe-os update` (update existing install). Setup creates encryption keys, configures cloud, runs first sync. Update just replaces code and restarts services. They are completely different commands."
+  },
+  {
+    title: "First install \u2014 setup wizard and license activation",
+    domain: "operations",
+    priority: "p1",
+    content: "Fresh install: `npm install -g @askexenow/exe-os` then run `exe` to start the setup wizard. The wizard prompts for: encryption passphrase (creates master key), license key (exe_sk_* from AskExe team), COO name, and optional team members. No license key = free tier (1 employee, 5K memories). After setup: hooks install automatically, MCP server registers in ~/.claude.json, daemon starts. Verify health: run `exe-os healthcheck` or use mcp_ping() tool."
+  },
+  // --- Operations ---
+  {
+    title: "Managers must supervise deployed workers",
+    domain: "workflow",
+    priority: "p0",
+    content: `Every manager (COO/CTO/CMO) who dispatches work to a worker MUST actively monitor them. Check tmux capture-pane every 10 minutes. Verify they're working, not stuck. If idle at prompt with in_progress task \u2192 send intercom. If stuck \u2192 unblock or escalate. "Standing by" without checking is negligence.`
+  },
+  {
+    title: "COO boot health check \u2014 memory, cloud sync, daemon on every launch",
+    domain: "workflow",
+    priority: "p0",
+    content: "On every /exe boot, COO MUST check system health BEFORE other work: (1) daemon \u2014 is exed PID alive, (2) cloud sync \u2014 grep workers.log for recent cloud-sync errors, (3) memory count \u2014 total in DB, (4) sync delta \u2014 local vs cloud storage_bytes. Report as 4-line status table. If ANY check fails, surface to founder immediately. Do not proceed to tasks until health confirmed."
+  },
+  {
+    title: "exe-build-adv mandatory for 3+ files",
+    domain: "workflow",
+    priority: "p0",
+    content: "exe-build-adv is MANDATORY for ALL work touching 3+ files. Run /exe-build-adv --auto BEFORE implementation. Pipeline: Spec \u2192 AC \u2192 Tests \u2192 Evaluate \u2192 Fix. No multi-file feature ships without pipeline artifacts. No exceptions \u2014 managers reject work without them."
+  },
+  {
+    title: "Code context first for repository orientation",
+    domain: "workflow",
+    priority: "p1",
+    content: "Before broad repo exploration, symbol tracing, blast-radius review, or codebase Q&A, agents should use the consolidated code_context MCP tool instead of manual grep/read loops. Use action=index or stats to refresh/check the index; action=search with query, limit, offset, languages, paths, refresh_index for fresh multi-language code/doc search; action=trace for symbol imports/dependents; action=blast_radius for impact analysis before edits. CLI parity exists via exe-os code-context init|index|status|stats|search|doctor. Keep code_context separate from durable employee memory: promote only validated decisions, procedures, or lessons into store_memory/commit_memory."
+  },
+  {
+    title: "Commit discipline \u2014 never leave verified work floating",
+    domain: "workflow",
+    priority: "p1",
+    content: "After any code-change batch passes typecheck/tests/build, run git status, summarize changed files, and commit with a clear message before ending the session. If work must remain uncommitted for review/dogfood, explicitly say so, list the files, and state the blocker. Never imply work is complete while verified changes are still floating locally."
+  },
+  {
+    title: "Desktop and TUI are the same product",
+    domain: "architecture",
+    priority: "p0",
+    content: "Desktop and TUI are the SAME product in different renderers. Same data contracts, same interactions, same acceptance criteria. Desktop tab specs in ARCHITECTURE.md ARE the TUI specs. When building TUI, cross-reference Desktop spec. Different tab names, identical behavior. Never treat them as separate products."
+  },
+  // --- Orchestration golden path ---
+  {
+    title: "Task lifecycle \u2014 the golden path every agent follows",
+    domain: "workflow",
+    priority: "p0",
+    content: "create_task is dispatch + delivery. Task lifecycle: open \u2192 in_progress (you start) \u2192 done (update_task when finished) \u2192 needs_review (reviewer nudged) \u2192 closed (COO only via close_task). DB is the reliable delivery \u2014 intercom is just a speedup nudge. If you finish a task, self-chain: check for next task immediately (step 7). Never wait for a nudge. Never say 'standing by.'"
+  },
+  {
+    title: "Review chain \u2014 managers must actively pull completed work, never wait for nudges",
+    domain: "workflow",
+    priority: "p0",
+    content: "When you dispatch work, you OWN the review. Check list_tasks(status='needs_review') on EVERY prompt \u2014 don't wait for intercom nudges (they're unreliable). When a task shows needs_review: (1) read the deliverable (git diff in worktree, exe/output/ files, or task result summary), (2) verify it works (tsc, build, run), (3) close_task if good or create a fix task if not. Reviews sitting >30 minutes is a pipeline stall. The whole chain: worker calls update_task(done) \u2192 system flags needs_review \u2192 manager pulls and verifies \u2192 close_task \u2192 COO reviews manager's work \u2192 merge to main. Every level actively pulls \u2014 nobody waits."
+  },
+  {
+    title: "Intercom is a speedup, not delivery \u2014 DB is the source of truth",
+    domain: "architecture",
+    priority: "p0",
+    content: "Tasks live in the DB. Intercom (tmux send-keys) is fire-and-forget \u2014 it may fail, get garbled, or arrive mid-work. Never rely on intercom for task delivery. The UserPromptSubmit hook checks the DB for new tasks on every prompt. Your operating procedures step 7 says check for next work. The daemon nudges idle agents as a speedup. If you have no tasks, you found them all."
+  },
+  // --- Encryption key + cloud sync ---
+  {
+    title: "Encryption key lives in Keychain, not on disk \u2014 never expose the recovery phrase",
+    domain: "security",
+    priority: "p0",
+    content: "The master encryption key is stored in macOS Keychain (Secure Enclave) or Linux secret-tool \u2014 NOT as a file. There is no ~/.exe-os/master.key on modern installs. If an older install had one, it was auto-migrated to Keychain and the file deleted. Device linking uses a 24-word BIP39 recovery phrase: Device 1 runs `exe-os cloud link --show-full` in their local Terminal to reveal it, Device 2 runs `exe-os cloud` and pastes the phrase to import the key into its own Keychain, then cloud sync pulls encrypted memories. NEVER display, log, or return the recovery phrase in agent output. MCP tools are hardened \u2014 they cannot reveal it. If the user needs the phrase, tell them: 'Run exe-os cloud link --show-full in your Terminal.' If searching for master.key returns nothing, that is CORRECT \u2014 the key is in Keychain."
+  },
+  {
+    title: "Cloud endpoint is cloud.askexe.com \u2014 not askexe.com/cloud",
+    domain: "architecture",
+    priority: "p1",
+    content: "All cloud API calls (auth, sync, licensing, device registry, WebSocket) go to https://cloud.askexe.com, NOT https://askexe.com/cloud. This is a Cloudflare Workers Custom Domain that bypasses the zone-level managed challenge on askexe.com. Datacenter IPs (Hetzner, AWS, etc.) get HTTP 403 on askexe.com due to Bot Fight Mode, but cloud.askexe.com routes directly to the Worker before WAF rules evaluate. If a customer reports 403/challenge errors on cloud sync: verify they are on the latest exe-os version (cloud.askexe.com endpoint). Fix: `npm install -g @askexenow/exe-os@latest`. The EXE_CLOUD_ENDPOINT env var can override the endpoint if needed."
+  },
+  // --- MCP is the ONLY data interface ---
+  {
+    title: "MCP disconnect \u2014 ask the user, never work around it",
+    domain: "workflow",
+    priority: "p0",
+    content: "If MCP tools are unavailable, disconnected, or returning connection errors: STOP. Tell the user clearly: 'MCP server is disconnected. Please run /mcp to reconnect.' Do NOT attempt workarounds \u2014 no raw Node imports, no direct DB access, no CLI hacks, no daemon socket calls. MCP is the ONLY data interface. Working around it wastes time, hits bundling issues, and bypasses the contract boundary. Ask once, wait, proceed when reconnected."
+  },
+  // --- MCP Tool Catalog (Layer 0 — every agent knows what tools exist) ---
+  {
+    title: "MCP tool dispatch \u2014 all tools use action parameter",
+    domain: "tool-use",
+    priority: "p0",
+    content: 'exe-os MCP tools use consolidated action-based dispatch by default (19 tools). Call domain tools with an action parameter: memory(action="recall"), task(action="create"), config(action="list_employees"), etc. Legacy mode (108 separate tools like recall_my_memory, create_task) is still available via EXE_MCP_TOOL_SURFACE=legacy but will be removed in a future version. If you see specific tool names, call them directly \u2014 both surfaces are identical. Consolidated is the default and recommended surface.'
+  },
+  {
+    title: "MCP tools \u2014 memory, decision, and search",
+    domain: "tool-use",
+    priority: "p1",
+    content: `memory(action="recall") / recall_my_memory: search memories (semantic + FTS). Params: as_of (bi-temporal \u2014 what did I know at time X?), kind (decision|procedure|observation|raw|conversation|behavior), retrieval_mode (all|decisions_only|procedures_only|operational|recent_high_value). memory(action="ask_team") / ask_team_memory: search a colleague's memories. memory(action="store") / store_memory: persist a memory. Params: kind, procedure_for (domain tag for procedures). memory(action="commit") / commit_memory: high-importance, survives consolidation. Requires summary. memory(action="search") / search_everything: unified search across memories, tasks, entities, conversations. memory(action="session_context") / get_session_context: temporal window. Requires session_id + target_timestamp. memory(action="get_by_id"): fetch one memory by UUID with full untruncated text. memory(action="consolidate") / consolidate_memories: merge duplicate/related memories. memory(action="cardinality") / get_memory_cardinality: count memories per agent. memory(action="supersede"): replace an old memory with a new version (old_id + new text). decision(action="store") / store_decision: record an architectural decision (domain, decision, rationale). decision(action="get") / get_decision: retrieve a past decision by domain or query.`
+  },
+  {
+    title: "MCP tools \u2014 task orchestration",
+    domain: "tool-use",
+    priority: "p1",
+    content: 'task(action="create") / create_task: dispatch work (title, assigned_to, context). The ONLY dispatch path. Auto-spawns session. Params: blocked_by (task ID for dependency), parent_task_id (subtask hierarchy), reviewer, complexity (routine|standard|complex|critical), budget_tokens (max token cap), budget_fallback_model, spawn_runtime (override runtime: claude|codex|opencode), spawn_model (override model). task(action="list") / list_tasks: query tasks by status, assignee, project. task(action="get") / get_task: fetch full task details by task_id. task(action="update") / update_task: change status (in_progress, done, blocked, cancelled) + result summary. task(action="close") / close_task: finalize a reviewed task (COO only). task(action="checkpoint") / checkpoint_task: save progress state for crash recovery. task(action="resume") / resume_employee: re-spawn an employee session for an existing task.'
+  },
+  {
+    title: "MCP tools \u2014 knowledge graph (GraphRAG)",
+    domain: "tool-use",
+    priority: "p1",
+    content: 'graph(action="query_relationships") / query_relationships: find connections between entities. graph(action="entity_neighbors") / get_entity_neighbors: explore direct connections. graph(action="hot_entities") / get_hot_entities: most-referenced entities. graph(action="stats") / get_graph_stats: entity/relationship counts. graph(action="export") / export_graph: export for visualization (output_path, format). graph(action="merge_entities") / merge_entities: deduplicate entities (source_id, target_id). graph(action="similar_trajectories") / find_similar_trajectories: match patterns to past solutions.'
+  },
+  {
+    title: "MCP tools \u2014 identity, behavior, and support",
+    domain: "tool-use",
+    priority: "p1",
+    content: `identity(action="get") / get_identity: read an agent's exe.md (Layer 1 identity). identity(action="update") / update_identity: write an agent's exe.md. Identity > behavior. behavior(action="store") / store_behavior: record a correction or pattern (Layer 2 expertise). behavior(action="list") / list_behaviors: view active behaviors. behavior(action="deactivate") / deactivate_behavior: soft-delete a stale behavior. support(action="create_bug"): file a bug report. Required: title, description, severity (p0-p3). Optional: steps_to_reproduce, expected_behavior, actual_behavior. Auto-delivers to AskExe support. support(action="create_feature"): file a feature request. Required: title, description. Optional: use_case (why you need it), proposed_solution (how it could work). Include business impact if possible \u2014 it helps prioritization. Both create_bug and create_feature accept a 'product' param to file for any AskExe product: exe-os (default), exe-create, exe-wiki, exe-gateway, exe-crm, exe-build. support(action="list_my_bugs"): check status of YOUR filed bug reports \u2014 see which are open, triaged, or fixed with version number. support(action="list_my_features"): check status of YOUR filed feature requests \u2014 see which are open, planned, shipped, or closed with response notes from AskExe. support(action="health"): verify support server is reachable. When a bug shows status='closed' with a fixed_version, tell the founder: 'Bug X fixed in vY \u2014 run exe-os update to get it.' When a feature shows status='shipped' with a shipped_version, tell the founder: 'Feature X shipped in vY \u2014 run exe-os update.' support(action="triage_bug"): AskExe-internal only. CRITICAL: triage uses triage_notes NOT notes.`
+  },
+  {
+    title: "MCP tools \u2014 communication and messaging",
+    domain: "tool-use",
+    priority: "p1",
+    content: 'message(action="send") / send_message: send context to another agent (NOT for actionable work \u2014 use task). message(action="acknowledge") / acknowledge_messages: mark messages as read. reminder(action="create") / create_reminder: set a reminder (text, due_date). Shown in boot brief. reminder(action="list") / list_reminders: view pending reminders. reminder(action="complete") / complete_reminder: mark done (reminder_id). session(action="events") / get_session_events: view session event log (session_id). session(action="last_response") / get_last_assistant_response: get most recent response.'
+  },
+  {
+    title: "MCP tools \u2014 wiki, documents, CRM, and data",
+    domain: "tool-use",
+    priority: "p1",
+    content: 'wiki(action="list") / list_wiki_pages: list wiki pages (workspace). wiki(action="get") / get_wiki_page: read a wiki page (workspace, title or document_id). document(action="ingest") / ingest_document: import a file as memory chunks (workspace_id, filename, chunks). document(action="list") / list_documents: browse documents (workspace_id). document(action="purge") / purge_document: remove a document (document_id). document(action="set_importance") / set_document_importance: adjust chunk scores. document(action="rerank") / rerank_documents: re-score relevance (query, candidates). crm(action="list_people|get_person|list_tables|describe_table"): CRM records from exe-db. raw_data(action="list_sources|query|get"): read raw landing-pad events. gateway(action="send_whatsapp") / send_whatsapp: send WhatsApp message (recipients, message). gateway(action="query_conversations") / query_conversations: search conversations across channels. gateway(action="query_company_brain") / query_company_brain: unified RAG across company knowledge.'
+  },
+  {
+    title: "MCP tools \u2014 admin, config, and operations",
+    domain: "tool-use",
+    priority: "p1",
+    content: 'config(action="list_employees"): view roster. config(action="set_agent_config"): view or change per-agent runtime + model. Call with no args to show all agents. config(action="agent_spend"): token usage per agent. config(action="daemon_health"): check exed status. config(action="license_status"): check license. config(action="cloud_sync"): force sync. Supports cloud_action param: status|sync|reupload. config(action="memory_audit"): health check (dupes, null vectors). config(action="run_consolidation"): trigger memory consolidation. config(action="worker_gate"): check spawn slot availability \u2014 alive/stale/reserved counts vs max. Use before dispatching. config(action="auto_wake_status"): orphaned tasks, blocked tasks, auto-wake retry status. config(action="orchestration_phase"): view/change org phase (phase_1_coo|phase_2_executives|phase_3_parallel_org). config(action="company_procedure", subaction="store|list|deactivate"): manage company procedures. config(action="global_procedure"): list all procedures (platform + company). config(action="create_trigger|list_triggers"): scheduled agent jobs. config(action="export_orchestration|import_orchestration"): portable org state. diagnostics(action="healthcheck|doctor|status_brief|check_update|cloud_status"): system diagnostics. diagnostics(action="pending_work_summary"): pending reviews + messages + notifications in one call. diagnostics(action="rename_employee"): rename an agent across all systems (roster, identity, DB, symlinks). diagnostics(action="tool_search"): semantic tool discovery \u2014 find relevant MCP tools by natural language query. diagnostics(action="drift"): identity drift detection \u2014 score how far an agent has drifted from its role. mcp_ping(): daemon health + license status + tool usage stats.'
+  }
+];
+var PLATFORM_PROCEDURE_TITLES = new Set(
+  PLATFORM_PROCEDURES.map((p) => p.title)
+);
+
+export {
+  PLATFORM_PROCEDURES,
+  PLATFORM_PROCEDURE_TITLES
+};

package/dist/chunk-6WTMJAG3.js

@@ -0,0 +1,171 @@
+import {
+  EXE_AI_DIR,
+  init_config
+} from "./chunk-KVPG5UT6.js";
+
+// src/lib/mcp-transport-health.ts
+init_config();
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var MCP_HTTP_EVENTS_PATH = path.join(EXE_AI_DIR, "mcp-http-events.jsonl");
+var MCP_MONITOR_DIR = path.join(EXE_AI_DIR, "monitor");
+var MCP_TRANSPORT_SUMMARY_PATH = path.join(MCP_MONITOR_DIR, "mcp-transport-summary.json");
+var DEFAULT_EVENT_READ_BYTES = 256 * 1024;
+var DEFAULT_EVENT_MAX_BYTES = 1024 * 1024;
+var EVENT_READ_BYTES = parsePositiveInt(process.env.EXE_MCP_HTTP_EVENT_READ_BYTES, DEFAULT_EVENT_READ_BYTES);
+var EVENT_MAX_BYTES = parsePositiveInt(process.env.EXE_MCP_HTTP_EVENT_MAX_BYTES, DEFAULT_EVENT_MAX_BYTES);
+function parsePositiveInt(value, fallback) {
+  if (!value) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function readTailText(filePath, maxBytes) {
+  const stats = statSync(filePath);
+  if (stats.size <= maxBytes) return readFileSync(filePath, "utf8");
+  const fd = openSync(filePath, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(maxBytes);
+    readSync(fd, buffer, 0, maxBytes, stats.size - maxBytes);
+    const text = buffer.toString("utf8");
+    const firstNewline = text.indexOf("\n");
+    return firstNewline >= 0 ? text.slice(firstNewline + 1) : text;
+  } finally {
+    closeSync(fd);
+  }
+}
+function rotateMcpHttpEventLogIfNeeded() {
+  if (!existsSync(MCP_HTTP_EVENTS_PATH)) return;
+  const stats = statSync(MCP_HTTP_EVENTS_PATH);
+  if (stats.size <= EVENT_MAX_BYTES) return;
+  const keepBytes = Math.min(EVENT_READ_BYTES, EVENT_MAX_BYTES);
+  const tail = readTailText(MCP_HTTP_EVENTS_PATH, keepBytes);
+  writeFileSync(MCP_HTTP_EVENTS_PATH, tail, "utf8");
+}
+function readPackageVersion() {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  const { root } = path.parse(dir);
+  while (dir !== root) {
+    const pkgPath = path.join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return parsed.version ?? "unknown";
+      } catch {
+        return "unknown";
+      }
+    }
+    dir = path.dirname(dir);
+  }
+  return "unknown";
+}
+function inferMcpRuntime(input) {
+  const text = [input.runtimeHeader, input.userAgent, input.agentId, input.clientName].filter(Boolean).join(" ").toLowerCase();
+  if (text.includes("codex")) return "Codex";
+  if (text.includes("claude")) return "Claude";
+  if (text.includes("opencode") || text.includes("open-code")) return "OpenCode";
+  return "Unknown";
+}
+function getMcpToolFamily(toolName) {
+  if (!toolName) return "unknown";
+  if (/task|employee|review|checkpoint|resume/i.test(toolName)) return "task";
+  if (/memory|consolidat|document|search_everything|get_session_context/i.test(toolName)) return "memory";
+  if (/config|daemon|worker|auto_wake|license|trigger|starter|orchestration|cloud_sync|backup/i.test(toolName)) return "config";
+  if (/message|whatsapp|conversation|gateway/i.test(toolName)) return "gateway";
+  if (/wiki|crm|raw_data|person|people/i.test(toolName)) return "company-data";
+  if (/graph|entity|relationship|trajectory/i.test(toolName)) return "graph";
+  if (/identity|behavior|decision|procedure/i.test(toolName)) return "cognition";
+  if (/ping|health/i.test(toolName)) return "health";
+  return "other";
+}
+function parseMcpHttpEventLines(raw, limit = 200) {
+  const lines = raw.trim().split("\n").filter(Boolean).slice(-limit);
+  const events = [];
+  for (const line of lines) {
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return events;
+}
+function readMcpHttpEvents(limit = 200) {
+  if (!existsSync(MCP_HTTP_EVENTS_PATH)) return [];
+  const raw = readTailText(MCP_HTTP_EVENTS_PATH, EVENT_READ_BYTES);
+  return parseMcpHttpEventLines(raw, limit);
+}
+function summarizeMcpTransport(events = readMcpHttpEvents()) {
+  const lastServerStartIndex = events.map((event) => event.message).lastIndexOf("server_started");
+  const scopedEvents = lastServerStartIndex >= 0 ? events.slice(lastServerStartIndex) : events;
+  const activeSessionEvent = [...scopedEvents].reverse().find((event) => typeof event.activeSessions === "number");
+  const successfulToolCalls = scopedEvents.filter((event) => event.message === "tool_call_ok");
+  const lastSuccessfulToolCall = successfulToolCalls.at(-1) ?? null;
+  const summary = {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    version: readPackageVersion(),
+    scope: "local",
+    privacy: "metadata_only",
+    eventLogPath: MCP_HTTP_EVENTS_PATH,
+    activeSessions: activeSessionEvent?.activeSessions ?? null,
+    sessionsCreated: scopedEvents.filter((event) => event.message === "session_initialized").length,
+    sessionsClosed: scopedEvents.filter((event) => event.message === "session_closed").length,
+    missingSessionErrors: scopedEvents.filter((event) => event.message?.includes("missing MCP session")).length,
+    staleSessionErrors: scopedEvents.filter((event) => event.message?.includes("stale or unknown")).length,
+    transportErrors: scopedEvents.filter((event) => event.level === "warn" || event.level === "error").length,
+    lastSuccessfulHandshake: scopedEvents.filter((event) => event.message === "session_initialized").at(-1)?.timestamp ?? null,
+    lastSuccessfulToolCall: lastSuccessfulToolCall?.timestamp ?? null,
+    lastSuccessfulToolCallByRuntime: {},
+    lastSuccessfulToolCallByAgent: {},
+    lastSuccessfulToolCallByFamily: {},
+    activeSessionsByRuntime: {},
+    recentWarnings: scopedEvents.filter((event) => event.level === "warn" || event.level === "error").slice(-10),
+    remediation: [
+      "If MCP tools fail with missing/stale session, reconnect the MCP client (/mcp or restart the runtime).",
+      "Do not access the database directly; MCP is the only data interface.",
+      "Check get_daemon_health or exe-healthcheck for daemon/MCP endpoint status before retrying work."
+    ]
+  };
+  const createdBySession = /* @__PURE__ */ new Map();
+  for (const event of scopedEvents) {
+    if (event.message === "session_initialized" && event.sessionId) createdBySession.set(event.sessionId, event);
+    if ((event.message === "session_closed" || event.message === "session_expired") && event.sessionId) {
+      createdBySession.delete(event.sessionId);
+    }
+  }
+  for (const event of createdBySession.values()) {
+    const runtime = event.runtime ?? "Unknown";
+    summary.activeSessionsByRuntime[runtime] = (summary.activeSessionsByRuntime[runtime] ?? 0) + 1;
+  }
+  for (const event of successfulToolCalls) {
+    if (event.runtime) summary.lastSuccessfulToolCallByRuntime[event.runtime] = event.timestamp ?? "";
+    if (event.agentId) summary.lastSuccessfulToolCallByAgent[event.agentId] = event.timestamp ?? "";
+    if (event.toolFamily) summary.lastSuccessfulToolCallByFamily[event.toolFamily] = event.timestamp ?? "";
+  }
+  return summary;
+}
+function writeMcpTransportSummary(events) {
+  try {
+    mkdirSync(MCP_MONITOR_DIR, { recursive: true });
+    writeFileSync(MCP_TRANSPORT_SUMMARY_PATH, JSON.stringify(summarizeMcpTransport(events), null, 2) + "\n");
+  } catch {
+  }
+}
+function recordMcpHttpEvent(event) {
+  try {
+    mkdirSync(EXE_AI_DIR, { recursive: true });
+    const enriched = { timestamp: (/* @__PURE__ */ new Date()).toISOString(), ...event };
+    appendFileSync(MCP_HTTP_EVENTS_PATH, JSON.stringify(enriched) + "\n");
+    rotateMcpHttpEventLogIfNeeded();
+    writeMcpTransportSummary(readMcpHttpEvents());
+  } catch {
+  }
+}
+
+export {
+  inferMcpRuntime,
+  getMcpToolFamily,
+  readMcpHttpEvents,
+  summarizeMcpTransport,
+  writeMcpTransportSummary,
+  recordMcpHttpEvent
+};