# Connect agents to Company OS

How to connect coding agents and terminals (Claude Code, Codex, OMP, Cursor,
Windsurf, Gemini CLI, other MCP clients, the Tern terminal plugin, and remote
clients such as Grok) to Company OS, and how each connection is governed.

Company OS owns company identity, policy, approvals, and the ledger. The agent
brings its own model. Connecting an agent never gives it approval authority.

Commands use `companyos` (the package also installs `company-os`; same CLI). In
a source checkout, `./company-os` runs the same verbs.

## 1. Connection or governed run

These are three different things.

| | Companion MCP connection | OMP read-only profile | Governed run (AgentChat) |
|---|---|---|---|
| Clients | Claude Code, Codex, Cursor, Windsurf, Gemini CLI, generic MCP | OMP, opened by hand | OMP TUI opened by `companyos chat` |
| Command | `companyos connect <client>` | `companyos connect omp` | `companyos chat` |
| Identity | Host principal commissioned by the Company Passport; credential in `HSMII_HOME` | Your CLI session (`companyos login`), bound to one company | A run admitted by the Company OS host |
| Tools | Company OS MCP catalog, limited by the host principal's scopes | 7 read tools | Run-grant-limited MCP profile plus a native action guard |
| Mutations | Allowed per tool; each needs `confirm=true` by default; the host still enforces policy and approvals | None | Each tool call is authorized by the host before it runs and settled after |
| Receipts | Ordinary ledger records for calls the host accepts | None; not an accountable run | Host authorization and settlement receipts, plus the run execution ledger |

What connecting gives an agent:

- Governed Company OS tools: tasks, memory, the tool catalog workflow, run
  events, trace queries, approval and HITL endpoints, and the Gestion Velora
  customer-intake and email handoff. `tool-definitions.ts` defines 75 tools (my
  count); 47 are classed read-only. `HSM_COMPANY_OS_MCP_TOOLS` (comma-separated
  names, at most 40) narrows what a server registers.
- Company context: the server publishes an operator contract at MCP
  initialization (identify, understand, govern, simulate, authorize, execute,
  verify, record). Read-only work stops after grounded understanding; mutations
  must leave independently verified task-trail evidence.
- Results in a `hsm.company_os.result.v1` envelope with a Markdown fallback. A
  successful call is not treated as verification.
- Approvals stay human ([section 4](#4-approval-model-for-agents)).

What connecting does not give an agent: a run grant, per-action receipts, or any
way to decide an approval. A manual OMP session from `connect omp` "remains read
only and does not create an accountable run."

A governed run: `companyos chat` admits a terminal run through the host, then
opens the installed OMP TUI in the current directory. Each governed MCP callback
sends its signed run grant to the host's `capability-actions/authorize` route
before the tool handler runs, and the host settles the exact action afterward. It
checks scope, expiry, company, run status, grant issuance, revocation, and a
matching unsettled action receipt before dispatch.

Known limit (`docs/company-os/OMP_GOVERNED_DRIVER.md`, evidence from 2026-10-03):
the host action boundary was shown (an authorized and settled read; a native
shell write denied before the effect, with a pending approval), but model-step
receipts and turn receipt parity were not. The terminal client "must not
advertise a complete governed receipt until a fresh installed run returns one
from the host."

### Runtimes Company OS can drive

The reverse direction: Company OS launching a vendor CLI. These adapter
manifests exist in `src/company_os/adapter_protocol.rs`; the external runner
contract is in `docs/company-os/EXTERNAL_ADAPTER_LANE.md`.

Vendor CLI adapters: `vendor_cli:codex` (Codex CLI), `vendor_cli:claude_code`
(Claude Code CLI), `vendor_cli:gemini` (Gemini CLI), `vendor_cli:opencode`
(OpenCode adapter), and `vendor_cli:openclaw` (OpenClaw 2.0 Agent CLI).

An `external` worker (webhook or bridged) lets any runner compute and report
back through Company OS APIs. OMP is driven through `companyos chat`.

## 2. Quick start per client

Prerequisites: Node 20 or later. For OMP and Tern, a CLI session:

```bash
companyos login --company COMPANY_ID
companyos login --device          # headless: open the shown Console URL, enter the code
```

`login` runs an Authorization Code + PKCE request in the Console and creates a
separate scoped CLI worker: a one-hour access credential and a rotating refresh
credential, of which only the refresh envelope is stored.

### Claude Code, Codex, Cursor, Windsurf, Gemini, generic

```bash
npx --yes @hsm/company-os-mcp-server connect codex
npx --yes @hsm/company-os-mcp-server connect claude
# or, with the CLI installed:
companyos connect claude|codex|cursor|windsurf|gemini|generic \
  [--project-dir PATH] [--install-dir PATH] [--api-base URL] [--open] [--no-start]
```

The README describes the `npx` form as available "after the package is
published". `connect`:

1. Runs the installer and Compose definition embedded in that exact npm release,
   pulls the matching versioned Company OS image, starts Postgres and
   `hsm_console` in `companion` mode, and verifies ledger health
   (`/api/company/health` must report Postgres ok). It fetches nothing mutable
   from the source repository.
2. Writes `companyos.integration.json` in the project directory, then merges a
   `company-os` entry into the client's MCP configuration, keeping other servers.

No provider key or model setting is requested; the host supplies its own model.

| Flag | Effect |
|---|---|
| `--no-start` | Do not start the stack; only regenerate host configuration. Use when the stack already exists. |
| `--project-dir PATH` | Directory to write configuration into. Default: current directory. Windsurf's file is global, so it is not affected. |
| `--api-base URL` | Company OS API origin written to the config. Default `http://127.0.0.1:3847`. |
| `--install-dir PATH` | Install and auth directory (becomes `HSMII_HOME` in the generated config). |
| `--installer PATH` | Use a specific installer script instead of the packaged one. |
| `--open` | Open the optional Console afterward. By default the command stays in the terminal. `--no-open` wins over `--open`. |

`COMPANY_OS_IMAGE` remains an explicit operator override for prerelease or
private-registry testing.

| Client | File written | Next step printed |
|---|---|---|
| `claude` | `<project>/.mcp.json` (entry has `"type": "stdio"`) | Reload Claude Code in this project |
| `codex` | `<project>/.codex/config.toml`, between `# BEGIN COMPANY OS MANAGED` and `# END COMPANY OS MANAGED` | Reload Codex in this project |
| `cursor` | `<project>/.cursor/mcp.json` | Reload Cursor (Settings, MCP shows `company-os`) |
| `gemini` | `<project>/.gemini/settings.json` | Restart Gemini CLI in this project |
| `windsurf` | `~/.codeium/windsurf/mcp_config.json` | Reload Windsurf (Cascade, MCP servers shows `company-os`) |
| `generic` | Nothing; prints the `mcpServers` entry | Paste it into your MCP host's configuration |

Every entry is a stdio server running
`npx --yes --package @hsm/company-os-mcp-server@<version> company-os-mcp-server`,
with `HSM_COMPANY_API_BASE` (and `HSMII_HOME` when set) in `env`. After reload,
ask the client to start the Company Passport. Re-running `connect` reuses an
existing `companyos.integration.json`; flags override its values.

### OMP

```bash
companyos login --company COMPANY_ID
companyos connect omp [--agent-dir PATH]
companyos mcp doctor --client omp
```

`connect omp` verifies the selected company through the host, starts the
CLI-bound MCP server for a live `company_os_health` and `company_os_get_company`
call, refreshes `~/.omp/agent/mcp.json` (or `--agent-dir PATH`, or
`PI_CODING_AGENT_DIR`), and runs `omp plugin doctor`. A failed host, CLI, or MCP
probe leaves the profile untouched; a doctor failure reports an error after the
profile is written.

The profile runs `companyos mcp serve --stdio` and holds no bearer, principal
token, or refresh token. The server refreshes the CLI session on each call and
refuses further calls if the session expires, is revoked, or changes company. Its
7 tools (`src/cli-mcp-scope.ts`): `company_os_health`, `company_os_get_company`,
`company_os_list_tasks`, `company_os_get_task`, `company_os_list_receipts`,
`company_os_show_receipt`, `company_os_verify_receipt`. Rerun
`companyos mcp connect omp` to refresh an older profile.

For governed OMP work use `companyos chat`, not this profile:

```bash
companyos chat                       # admitted run, opens the OMP TUI here
companyos chat --prompt "TEXT"       # one noninteractive turn
companyos chat --start "TEXT"        # TUI opens with TEXT as the first message
companyos chat --thread-id UUID      # resume a host thread
```

On another machine, log in remotely:
`./company-os login --console-url https://<company-os-host> --device`. That login
needs the `company_os:tools` scope and a non-loopback HTTPS endpoint.

### `companyos connect` or `companyos mcp connect`

Same code path. `companyos mcp connect CLIENT` re-parses its arguments as
`companyos connect CLIENT ...`, and its help says "Other clients use the existing
companyos connect path." Both accept `omp, codex, claude, cursor, windsurf,
gemini, generic`; `mcp connect` always prints JSON.

Source states no preference. Suggested convention: `companyos connect` in setup
instructions (the README leads with it), `companyos mcp ...` for `status`,
`doctor`, and `tools` afterward. The Tern palette runs `mcp connect`.

`--agent-dir` is OMP only. The other flags apply to the non-OMP clients, and
`connect omp` rejects boolean options.

## 3. First use: the Company Passport

On first use, the MCP tools run the durable Company Passport flow. The operating
contract tells the agent to call `company_os_list_companies` first and to offer
the Passport only if no commissioned company exists. In order:

| Step | Tool | Purpose |
|---|---|---|
| 1 | `company_passport_start` | Start a durable session before a company exists |
| 2 | `company_passport_answer` | Save the reviewed session, with optimistic versioning |
| 3 | `company_passport_prepare` | Store the server-normalized draft for human review. It "does not commission a company or mint authority." |
| 4 | `company_passport_answer` | Record the human's explicit authority and change-set confirmation |
| 5 | `company_passport_commission` | Commission the exact stored, reviewed version. Needs `confirm`. |

Helpers: `company_passport_get` re-reads a session and version;
`company_passport_industry_packs` lists the industry packs.

"Authority and change-set confirmations must reflect explicit human answers,
never model inference." The agent must never request, repeat, or display
credential material.

**What commissioning creates**

- A distinct host agent: `claude-code-host` (adapter `claude-code`) or
  `codex-host` (adapter `codex`), role `worker`.
- Eight delegated scopes, each expiring in 720 hours (30 days):
  `company_os:tasks`, `company_os:memory`, `company_os:customers`,
  `company_os:connectors`, `company_os:tools`, `company_os:workspace_files`,
  `company_os:validation`, `work_packages:workflow`.
- A host principal credential, also 720 hours, and an owner credential whose
  expiry the server sets.

`company_passport_commission` takes `host` of `claude` or `codex` only. Source
does not describe commissioning for Cursor, Windsurf, Gemini CLI, or generic
clients.

**Credentials and where they live**

- Commissioning writes `company-os-owner.binding.json` and
  `company-os-host.binding.json` under `HSMII_HOME` (default `~/.hsm-ii`), each
  private with mode 0600. Credentials are never written to `.mcp.json`,
  `.codex/config.toml`, command arguments, or MCP results.
- The server refuses a credential file that is not a regular non-symlink file,
  has any group or other permission bit, or belongs to another user.
- Auth home lookup when reading: `HSM_COMPANY_OS_AUTH_HOME`, then `HSMII_HOME`,
  then `COMPANY_OS_INSTALL_DIR`, then `~/.hsm-ii`.
- The CLI login session is separate. On macOS its refresh envelope is a 0600 file
  under `~/Library/Application Support/Company OS/`; Linux and Windows use the
  OS credential store. It does not create `~/.hsm-ii`. `companyos logout`
  revokes every credential for that CLI worker, then deletes the envelope.

## 4. Approval model for agents

| `HSM_COMPANY_MCP_APPROVAL_MODE` | Behavior |
|---|---|
| unset | `strict` (default). Mutating and approval-sensitive tools return `approval_required` unless called with `confirm=true`. |
| `permissive` | Skips the check. README: only for trusted local automation. |
| `bound` | In the client code, not the README. A mutation must cite an `approval_id` that is approved, decided by someone other than its requester, unconsumed, and unexpired. The binding is consumed whether or not it verifies. |

`confirm=true` is an intent check, not authority. `src/client.ts` says it is
"asserted by whoever calls the tool, which may be a model, so `strict` is an
intent check, not an authority boundary." Authority is enforced by Company OS: it
refuses approval decisions for model-driven principals, and external effects need
a consumed human grant. The README states for the remote bridge: "A
model-supplied `confirm=true` is not human approval." The operating contract adds:
"Never treat the assistant's own proposal as approval." A CLI `--confirm` is not
approval either ("A CLI confirmation never grants authority").

Other rules:

- `company_os_call_tool` defaults to `dry_run=true`; the flow is
  `company_os_discover_tools`, `company_os_describe_tool`, `company_os_call_tool`.
  A real call needs `confirm=true` in strict mode.
- Direct mutations without dry-run support need a bounded change presented and
  current state read first (operating contract, step 4).
- The phone-call handoff tools need confirmation and reject raw transcript and
  recording parameters. `company_os_propose_email_reply` leaves the reply
  `pending_approval`; Company OS does not send it.

**Who decides.** A person, in the Console (Approvals inbox, `/workspace/approvals`)
or at a terminal:

```bash
companyos approvals --status pending
companyos approval show APPROVAL_ID
companyos approval approve|reject APPROVAL_ID [--reason TEXT] --confirm
companyos approval decide APPROVAL_ID --decision approved|rejected --confirm
```

The decision refreshes the authoritative inbox and binds your choice to the
server-stored presentation, subject, and request digests. Afterward:
`companyos receipt list|show|verify ID`, `companyos verify task|run ID`.

## 5. Check a connection

`companyos mcp` checks the selected CLI company's host, connector projection, and
a read-only stdio MCP handshake. It needs a CLI session. `--help` on any command
does not contact the host.

```bash
companyos mcp status                  # company, host, connectors, MCP handshake
companyos mcp doctor                  # each check, PASS or FAIL; nonzero exit on failure
companyos mcp doctor --client omp     # adds OMP version, plugin doctor, profile checks
companyos mcp tools --search task     # tools the CLI-bound session actually exposes
companyos mcp tools --quiet           # names only (also --json, --table)
companyos mcp connectors list         # host-owned connectors and OAuth state
companyos mcp connectors show|resources|prompts ID
companyos mcp serve --stdio           # the read-only server the OMP profile runs
```

- `--company-id UUID` selects the company bound to the CLI grant; `--json` prints
  the typed report.
- `doctor` check ids: `omp_version`, `omp_plugin_doctor`, `omp_profile` (OMP
  only), then `cli_grant`, `company`, `host`, `connectors`, `mcp_handshake`. The
  OMP checks run even if the host is down; the rest need a valid CLI session.
- `mcp status` and `mcp tools` inspect the CLI-bound read-only server (the OMP
  profile), not the companion server that Claude Code or Codex launch with
  `npx`. Check those in the client's own MCP view.
- `companyos mcp connectors enable|disable ID --confirm` (optional
  `--idempotency-key KEY`) asks the host, which rechecks authority and returns a
  receipt or a typed refusal. OAuth and reconnect are not in this CLI.
- Also: `companyos doctor` (client preflight plus server checks).
- After an OMP upgrade, run the offline smoke
  `node services/company-os-mcp-server/scripts/omp-compatibility-smoke.mjs` (after
  `npm --prefix services/company-os-mcp-server run build`). It uses a temporary
  profile and a dummy model credential and does not verify the live host.

## 6. Tern terminal plugin

`integrations/tern-companyos` makes governed AgentChat the main entry point and
adds a cockpit, palette actions, and read-only tools for Tern's assistant, Carly.

```bash
tern plugin link ./integrations/tern-companyos     # from the repository root
tern plugin list
tern plugin unlink companyos
```

Tern reloads linked plugins when files change. Every action runs the Company OS
command resolved in this order: `HSM_COMPANY_OS_CLI`; the checkout's
`scripts/company-os` through `/bin/bash` (`HSM_COMPANY_OS_REPO` or the checkout
the plugin is linked from); `$HOME/.local/bin/companyos`. Several actions run the
built operator CLI (`services/company-os-mcp-server/dist/company-os-cli.js`);
build it once with `npm --prefix services/company-os-mcp-server run build`.

Palette actions (search for **Company OS**). Each opens a new tab and leaves a
shell open so output stays visible.

| Action | Runs |
|---|---|
| Company OS AgentChat: Start governed chat | `companyos chat` |
| Connect Claude Code to Company OS | `companyos mcp connect claude` |
| Connect Codex to Company OS | `companyos mcp connect codex` |
| Connect OMP to Company OS (read-only) | `companyos mcp connect omp` |
| Check OMP connection | `companyos mcp doctor --client omp` |
| Log this computer in to Company OS | `companyos login` |
| Start Company OS | `companyos up` (starts or reuses local services, opens the Console) |
| Open Company OS approvals waiting on you | `approvals --status pending --table` |
| Open Company OS tasks, recent agent runs, receipts | `task list --table` (25), `ps --table` (20), `receipt list --table` |
| Open Company OS usage and cost; Run Company OS doctor | `cost`; `doctor` |
| Check Company OS readiness | `companyos status` |
| Open Company OS Console | `/workspace/start` on `127.0.0.1`, port `HSM_COMPANY_CONSOLE_PORT` or `3050`; does not start services |
| Open Company OS cockpit | Native block: workspace health and Beads queue. `Enter` on a bead runs `companyos chat --start "Work on Beads issue ..."` |

The OMP profile stays read-only. Use **Start governed chat** when a turn needs the
host-admitted run and its receipts. Approvals are listed by the palette but
decided in the Console or with `companyos approval approve|reject ID --confirm`.
Optional key binding: `"cmd+shift+g": "plugin.companyos.agentchat"` under
`keybinds` in Tern's `settings.json` (pick a free chord).

**Carly.** Every Carly request carries one context line (Company OS installed,
last known status, read the guide first). The plugin exports 16 tools under
`plugins.companyos`, the Tern maximum: 15 read-only tools and `open`.

- `guide(topic?)`: the plugin guide, `GUIDE.md`.
- `status()`: API host (`127.0.0.1:3847/api/company/health`) and Console
  (`/api/agent-chat-runtime`), checked separately.
- `tasks`, `task`, `approvals`, `runs`, `run` (views `what`, `why`, `timeline`,
  `inspect`, `events`), `receipts`, `verify` (task, run, or receipt).
- `memory` (`memory search`), `usage` (`cost`, `usage`, `stats`,
  `operator-status`), `beads` (`br ready|blocked|stats|show`), `tools`
  (`mcp tools`), `connectors` (`mcp connectors list`), `doctor`.
- `open(target, page?)`: opens a palette view or Console page for the person.

Each live read runs one command and returns
`{ok, command, output, truncated, stderr, hint}`, with `output` cut at about 9 KB.
Arguments go to argv, never a shell, and a value starting with `-` is refused, so
Carly cannot add `--confirm`. Carly never approves, sends, creates, or runs
anything; for a change it opens the matching view and a person acts. The plugin
does not read or store Company OS credentials.

## 7. Remote MCP bridge (Grok and other remote clients)

The package includes a stateful Streamable HTTP MCP server for a remote MCP
connector such as xAI/Grok. It reuses the stdio handlers and operator contract; it
is not a second agent runtime or policy engine. Start it after the API is up:

```bash
cd services/company-os-mcp-server
npm run build
HSM_COMPANY_API_BASE=https://company-os.internal \
HSM_COMPANY_ID=<company-uuid> \
HSM_COMPANY_PRINCIPAL_TOKEN=<server-held-principal-token> \
HSM_COMPANY_PRINCIPAL_COMPANY_ID=<company-uuid> \
HSM_COMPANY_OS_REMOTE_MCP_TOKEN=<strong-random-grok-token> \
npm run start:http
```

`company-os-mcp-http` is the installed bin for the same server.

| Setting | Default and rule |
|---|---|
| Endpoint | `http://127.0.0.1:3850/mcp`. Change with `HSM_COMPANY_OS_REMOTE_MCP_HOST`, `..._PORT`, `..._PATH`. |
| Inbound auth | `HSM_COMPANY_OS_REMOTE_MCP_TOKEN`, required. Accepted only as a bearer header, never forwarded to Company OS. A bad token gets HTTP 401 with `WWW-Authenticate: Bearer`. |
| Server-held credentials | `HSM_COMPANY_ID`, `HSM_COMPANY_PRINCIPAL_TOKEN`, and a matching `HSM_COMPANY_PRINCIPAL_COMPANY_ID` are required even for read-only. They can load from the private binding files. |
| Health | `GET /healthz`, unauthenticated. |
| Company binding | Each session is bound to the configured company; a request naming another `company_id` is refused. |
| Non-loopback bind | Also set `HSM_COMPANY_OS_REMOTE_MCP_ALLOWED_HOSTS`, or startup fails. `..._ALLOWED_ORIGINS` is optional. |
| Limits | `..._MAX_BODY_BYTES` (1048576); `..._MAX_REQUESTS_PER_MINUTE` (120 per source); session cap and idle timeout. |
| Approval mode | Always `bound`. Every mutation must cite an `approval_id` a human already decided; the model's `confirm=true` is not accepted. |

Put the bridge behind an HTTPS reverse proxy before giving the URL to Grok.

Default allowlist, read-only (16 tools, from `src/remote-mcp-config.ts`):

```text
company_os_health, company_os_list_companies, company_os_get_company,
company_os_get_document_profile, company_os_dashboard, company_os_list_tasks,
company_os_get_task, company_os_list_agent_runs, company_os_run_story,
company_os_list_run_surfaces, company_os_trace_query, company_os_search_memory,
company_os_list_approvals, company_os_show_approval, company_os_verify_task,
company_os_verify_run
```

Override with `HSM_COMPANY_OS_REMOTE_MCP_TOOLS` (comma-separated). A tool outside
the read-only set also needs `HSM_COMPANY_OS_REMOTE_MCP_ALLOW_MUTATIONS=1`, or
startup fails. Company OS confirmation, governance, approval, execution,
verification, and receipt checks still apply.

For the xAI Remote MCP connector, give it the HTTPS `server_url`, a list of
`allowed_tools`, and the same token as `HSM_COMPANY_OS_REMOTE_MCP_TOKEN` in
`authorization` (conceptual configuration in the package README).

Set `HSM_COMPANY_OS_CONSOLE_ORIGIN` (absolute HTTPS origin) to add Console links to
results; links are navigation only and grant no authority.

## 8. Troubleshooting

Messages are quoted from the source. Run `companyos mcp doctor` first; its
`Next:` line names the action.

| Symptom | Fix |
|---|---|
| `connect host must be one of claude, codex, cursor, windsurf, gemini, generic` | Use one of those, or `omp` (`companyos connect omp`). |
| `Company OS companion bootstrap failed: ...` | The embedded installer failed; the tail of its stderr is included. If the stack already exists, rerun with `--no-start`. |
| `Company OS health verification failed: HTTP <n>` or `... did not confirm Postgres` | The stack started but the ledger is not healthy. Check `GET /api/company/health` on the API base, then rerun `connect`. |
| `invalid Claude MCP config <path>` or `invalid mcpServers object in <path>` | The existing client config is invalid JSON or `mcpServers` is not an object. Fix the file; `connect` will not overwrite it. |
| `unsupported Company OS integration manifest: <path>` | `companyos.integration.json` does not match schema `hsm.company_os.integration.v1`. Fix or remove it, then rerun. |
| Client does not show `company-os` | Reload or restart the client as `connect` printed. Windsurf's file is global. |
| Agent says the Passport must start | No commissioned company exists. See [section 3](#3-first-use-the-company-passport). |
| `Company OS credential file must have mode 0600: <path>` | `chmod 600` the file; it must be a regular file you own. |
| Tool returns `approval_required` | Expected in strict mode. A person approves, then the agent retries with `confirm=true`. In `bound` mode, pass an `approval_id` a human already decided. |
| Agent wants to approve its own request | Not possible. Decide in the Console or with `companyos approval approve\|reject ID --confirm`. |
| `Company OS host is unreachable. Start or reconnect the host, then retry companyos connect omp.` | Start the host (`companyos up`), then retry. |
| `An authorized Company OS CLI session is required for OMP connection` | `companyos login --company COMPANY_ID`. |
| Doctor `cli_grant` fails | "Resolve the CLI session error, then run companyos mcp doctor." Log in again; a session can expire or be revoked. |
| Doctor `company` fails | "Reauthorize the selected company with companyos login --company ID." |
| Doctor `host` fails | "Start or reconnect the Company OS host, then retry companyos mcp doctor." |
| `OMP company-os profile is missing or stale at <path>; run companyos mcp connect omp` | Rerun `companyos mcp connect omp`. |
| `OMP version check failed: ...` or `OMP plugin doctor failed: ...` | Fix the OMP installation (is `omp` on `PATH`?), then `companyos mcp doctor --client omp`. |
| `Company OS CLI session changed; restart OMP to bind the new session` | Login or company changed under a running OMP. Restart OMP. |
| `MCP tool outside the CLI read-only scope: <names>` | Rerun `companyos mcp connect omp` to refresh the profile. |
| Governed chat refuses to start | "Governed terminal chat requires a loopback Company OS CLI session. Run `companyos login` against the local Company OS host." |
| `Company OS remote MCP configuration is missing <NAME>` | Set the named variable (`HSM_COMPANY_OS_REMOTE_MCP_TOKEN`, `HSM_COMPANY_ID`, `HSM_COMPANY_PRINCIPAL_TOKEN`, or `HSM_COMPANY_PRINCIPAL_COMPANY_ID`). |
| `Company OS remote MCP non-loopback binding requires HSM_COMPANY_OS_REMOTE_MCP_ALLOWED_HOSTS` | Set the allowlist, or bind to loopback behind a proxy. |
| `Remote MCP mutation tools require HSM_COMPANY_OS_REMOTE_MCP_ALLOW_MUTATIONS=1: <names>` | Remove those tools from the allowlist, or set the variable deliberately. |
| Tern: `workspace is not ready` | Run **Start Company OS**, then **Check Company OS readiness**. |
| Tern: `operator CLI is not built` | `npm --prefix services/company-os-mcp-server run build`. |
| Tern: Node not found | Set `HSM_COMPANY_OS_NODE`. |
| Tern: login or grant errors | Run **Log this computer in to Company OS**. |
| Tern: tools fail with `fetch failed` while the API answers | The Console is down or hung. Restart it, then **Start Company OS**. |
| Anything else | `companyos doctor`, or **Run Company OS doctor** in Tern. |