# Complete Company OS

This is the single truthful map for HSM-II Company OS. It consolidates the launch path, agent-chat path, worker defaults, tool surface, optional lanes, and known gaps.

Machine-readable source: [`config/company-os-truth.json`](../../config/company-os-truth.json).

Release claims are independently gated by the
[`Company OS maturity gates`](./COMPANY_OS_MATURITY_GATES.md). The nine-row
verifier fails closed on missing, stale, mismatched, incomplete, or tampered
evidence; component availability alone is not product maturity.

Native harness contract: [`native-snapshot-gepa-harness.md`](./native-snapshot-gepa-harness.md).

Native spine contract: [`HSM_NATIVE_SPINE.md`](./HSM_NATIVE_SPINE.md).

Market-facing positioning: [`AGENTCHAT_BRANDING_AND_MARKETING.md`](./AGENTCHAT_BRANDING_AND_MARKETING.md).

## Product Definition

Company OS is the local-first operating spine for HSM-II:

- Company Console is the operator front door.
- `hsm_console` is the API and execution service.
- Postgres is the world model and ledger.
- Agent-chat is the conversation surface into the same system.
- The HSM native worker is the default brain loop.
- `company_*` tools are the capability boundary.
- Memory, workspace, connectors, policy, traces, and eval/promotion are part of the same loop.

Optional systems like OpenRouter, Claude/Ax, RLM REPL, Harbor, SGLang, GraphJin, graphify, and OpenCode are useful extensions. They are not required for the core Company OS to be complete.

**Company OS v1 release posture:** ship the Rust-native monolith as the local-first spine. Power
Mode makes safe advanced surfaces visible on localhost; provider-backed and execution-changing
lanes remain explicit. Rustler is a production-ready thin optional bridge for helpers/resources,
while heavy `run_skill/2` execution stays unavailable until BEAM-owned `ConsoleState` and runtime
ownership are proven.

OpenHands is not a Company OS dependency. OpenHands-style ideas such as terminal/file/browser tools, sandboxed agent execution, and GEPA-callable harnesses map to HSM-II's own native ReAct worker, Rust tool registry, run-event ledger, snapshot artifacts, eval packs, and promotion gates.

## One Command

```bash
./company-os
```

The command starts or reuses the local workspace and prints one ready URL.
`scripts/company-os-up.sh` remains the internal supervisor for diagnostics and
test harnesses, not the default product command.

Default profile:

| Setting | Default | Meaning |
| --- | --- | --- |
| Chat provider | `openrouter` | Canonical free-model provider |
| Model | `openai/gpt-oss-120b:free` | Canonical OpenRouter-free chat/worker model |
| Execution backend | `hsm_native_worker` | HSM-II native execution path |
| Worker backend | `hsm_native_worker` | HSM-II native ReAct worker |
| Claude/Ax harness | off | Enable explicitly with `HSM_CLAUDE_HARNESS=1` |
| Executor/RLM | off | Enable explicitly with `HSM_EXECUTOR=1` and `HSM_CONSOLE_CODE_AGENT=rlm_repl` |
| OpenRouter | on | Uses `OPENROUTER_API_KEY`; missing credentials degrade visibly |
| OpenCode escalation | off | Enable explicitly with `HSM_OPENCODE_ESCALATION=1` |

On localhost, Company Console Power Mode is enabled by default for visibility. It exposes
snapshots, promotion experiments, GEPA, dynamic plans, trace routing, ColGREP, and runtime mesh
status. It does not automatically enable RLM REPL, Ralph refinement, browser snapshot execution,
or cloud/provider lanes.

## Core Architecture

```mermaid
flowchart TB
  Cmd["./company-os"] --> Pg["Postgres world model"]
  Cmd --> Api["hsm_console API"]
  Cmd --> Ui["Company Console"]
  Cmd --> Model["OpenRouter openai/gpt-oss-120b:free"]

  Ui --> Chat["agent-chat"]
  Chat --> Worker["execute-worker"]
  Worker --> Native["HSM native worker\n(hsm_native_worker)"]
  Native --> Tools["company_* tools"]
  Native --> Model

  Tools --> Memory["memory + retrieval"]
  Tools --> Workspace["workspace files + artifacts"]
  Tools --> Connectors["connectors + credentials"]
  Tools --> Governance["policy + human gates"]
  Tools --> Runs["runs + traces + eval"]

  Memory --> Pg
  Workspace --> Pg
  Connectors --> Pg
  Governance --> Pg
  Runs --> Pg
```

## Component Truth Table

| Component | Used by one command? | Useful now? | Status |
| --- | --- | --- | --- |
| Company Console | Yes | Yes | Core |
| `hsm_console` API | Yes | Yes | Core |
| Postgres world model | Yes | Yes | Core |
| Agent-chat | Yes | Yes | Core |
| Native ReAct worker | Yes | Yes | Core |
| `company_*` tools | Yes | Yes | Core |
| Memory and workspace | Yes | Yes | Core |
| Governance, traces, eval hooks | Yes | Yes | Core |
| BaseLayer connector | Tool/catalog surface yes | Yes with provider running | Connected, provider-backed |
| Repo skills | Yes | Yes | Core, loaded via `HSM_SKILL_EXTERNAL_DIRS` |
| RLM REPL executor | No | Yes | Optional |
| `smol_code` | No | Yes | Eval-only |
| Claude/Ax harness | No | Yes | Optional sidecar |
| OpenRouter | No | Yes | Optional cloud lane |
| Harbor | No | Yes | Optional verifier |
| codegraph/graphify/GraphJin | Service-dependent | Yes when configured | Optional intelligence prefixes |
| SGLang/Nemotron | No | Experimental | Optional model lane |
| OpenCode escalation | No | Useful with auth | Optional escalation |
| DB intelligence preview | No | Useful but sensitive | Explicitly gated |
| Document parsing/OCR | No | Useful | Optional tool/docs lane |

## Operating Rule

The complete product is not "turn every subsystem on." The complete product is one reliable core loop:

```mermaid
flowchart LR
  Intent["operator intent"] --> Task["task/run record"]
  Task --> Context["memory + workspace + policy context"]
  Context --> Worker["native worker"]
  Worker --> Tool["company tool call"]
  Tool --> Evidence["run events + artifacts"]
  Evidence --> Gate["verifier / human gate"]
  Gate --> Promote["skill, memory, or runtime policy delta"]
  Promote --> Context
```

Everything outside that loop should either:

- feed context into the loop,
- expose a tool to the loop,
- verify the loop,
- or be documented as optional/experimental.

## Minimal Valuable Harness

Agent-chat now uses a small value contract before worker execution:

| Field | Purpose |
| --- | --- |
| `work_mode` | Classifies the turn as `research_brief`, `repo_diagnosis`, `decision_memo`, `document_extract`, `task_plan`, or `direct_answer` |
| `context_budget` | Caps context chars, tool calls, and evidence items by mode |
| `artifact_schema` | States the expected final artifact shape |
| `cheap_grader` | Defines low-cost checks for useful output |
| `promotion_gate` | Keeps skill promotion inert until repeated cheap-graded successes |

Retrieval-heavy modes can call `company_retrieval_program_run`. It composes cheap memory/workspace retrieval, creates a `retrieval_evidence` artifact, and persists it to shared company memory as an `artifact:briefing` row.

```mermaid
flowchart LR
  Turn["agent-chat turn"] --> Mode["work_mode + budget"]
  Mode --> Retrieve["company_retrieval_program_run"]
  Retrieve --> Evidence["retrieval_evidence artifact"]
  Evidence --> Worker["native ReAct worker"]
  Worker --> Output["artifact-shaped final output"]
  Output --> Grade["cheap grader"]
  Grade --> Promote["repeated-success promotion gate"]
```

## Council Verdict

The council direction is implemented as a **default operating contract**, not as a full product guarantee yet.

What is solid now:

- One canonical command opens the default Company OS path.
- Agent-chat routes substantive work through native ReAct by default.
- Work modes carry budgets, artifact schemas, cheap graders, and promotion gates.
- Retrieval-heavy work has one bounded tool, `company_retrieval_program_run`, that produces evidence artifacts.
- Postgres Company OS remains the ledger for company, task, memory, governance, DRI, run, and promotion state.
- Workspace run details mirror the same contract: intent, context budget, evidence artifact state, terminal outcome, owner/DRI signal, grade, promotion counter, and next operator decision.
- Runtime now badges optional lanes separately from the default native ReAct path.

What is not fully product-complete yet:

- Cheap graders are persisted on `agent_runs.meta`, but any autonomous skill write still needs the existing human/verifier promotion path.

## Operator Value Bar

Company OS is valuable only when it changes how a company is managed. The acceptance test for every new surface is:

| Bar | Product rule |
| --- | --- |
| One Company OS | A feature is product surface only when it reads/writes Company OS state for a `company_id`, or is clearly labeled optional/experimental. |
| DRI-first | High-stakes or cross-cutting work binds to a DRI, goal, task, governance event, or `requires_human` decision path. |
| Artifact over activity | Runs are useful when they produce decision-changing artifacts with evidence, not merely tool activity or long traces. |
| Workspace mirrors agent-chat | The workspace should show intent, context budget, evidence, terminal outcome, owner/DRI, and next decision. |

## Anti-Bloat Guardrails

These are the hard lines for keeping the harness economically useful:

| Risk | Guardrail |
| --- | --- |
| Multi-lane harness complexity | Native ReAct is default; RLM, Claude/Ax, Harbor, OpenRouter, SGLang, and OpenCode stay opt-in with explicit badges and reasons. |
| Big context injection | Work modes set context budgets; retrieval produces bounded evidence artifacts instead of prompt stuffing. |
| Always-on graph layers | Graph/intelligence layers produce context or proposals; Postgres Company OS remains the ledger. |
| Agent swarms | Spawn agents only when task graph, DRI, or capability refs justify delegation. |
| Generic memory everywhere | Memory writes are scoped and source-tagged; traces/evals become memory or skills only through gates. |
| Expensive reranker/API defaults | Local/cheap retrieval defaults first; paid rerankers/cloud APIs are opt-in with visible cost reasons. |
| Activity-first evals | Evals grade artifact quality, evidence, terminal outcome, and decision impact before raw activity. |
| Decisionless dashboards | Dashboards must change an operator decision or expose a required action. |

## Native Snapshot + GEPA Path

The pasted "OpenHands + GEPA + snapshots" architecture should be adapted as a native Company OS loop:

| Layer | Company OS native surface |
| --- | --- |
| Skill harness | `execute-worker` with HSM-II native ReAct |
| Tools | Rust tool registry, `company_*` tools, workspace/browser/session tools |
| Snapshot environment | `company_snapshot_session_run` plus Company OS blob/workspace artifacts |
| Snapshot serving | `/api/company/companies/{company_id}/snapshots` with hash/version metadata and replay API |
| Browser snapshot shim | `company_browser_snapshot_capture` via `HSM_BROWSER_SHIM_URL` |
| GEPA callable | `/api/company/companies/{company_id}/gepa/optimize`, meta-harness/eval-pack runner over agent-chat or task-worker turns |
| Trace store | `agent_runs`, `run_execution_events`, task telemetry, artifact grades |
| Promotion | Repeated successful cheap grades, `/promotion-experiments`, verifier/human approval, rollback records |

The rule is simple: use external agent frameworks as references, not as the operating dependency.

`company_snapshot_session_run` is the native worker snapshot primitive. It captures `workflow_snapshot` artifacts into shared Company OS memory, then `list`/`get` retrieves them for eval packs, GEPA optimization, and operator review. The dedicated snapshot service stores durable replay state with hash/version metadata.

## Native SDK + Runtime Contracts

Company OS now has one native contract for the four OpenHands-parity gaps that matter without inheriting OpenHands as a dependency:

| Surface | Native Company OS contract |
| --- | --- |
| SDK | `company-os-sdk/` exposes Python/TypeScript clients, OpenAPI, action-event methods, and markdown-agent helpers |
| Markdown agents | `schemas/company_os_agent_definition.v1.json` and `src/company_os/agent_definitions.rs` parse frontmatter tool/MCP/runtime declarations |
| Ephemeral sessions | `company_workspace_session_run` creates/gets/closes isolated session roots with uploads/artifacts metadata |
| Typed events | `schemas/company_os_action_event.v1.json` plus `run_execution_events` with `schema: hsm.company_os.action_event.v1` |
| Dynamic workflows | `company_dynamic_workflow_run` creates bounded workflow-plan artifacts for fan-out, verification, tournament, triage, loop, and eval patterns |

See `docs/company-os/native-sdk-agent-runtime-contract.md`.

## Native Dynamic Workflows

`company_dynamic_workflow_run` is the native answer to Claude-style dynamic workflows. It produces a typed `workflow_plan` artifact with pattern, budgets, DRI, quarantine, adversarial verification, stop conditions, artifact requirements, and terminal outcome.

Dynamic workflows are optional and should be used only when one ReAct turn is structurally weak: deep verification, large triage, tournament ranking, loop-until-done debugging, research fan-out, evals, or rule mining. They do not auto-spawn swarms.

See `docs/company-os/native-dynamic-workflows.md`.

## Known Gaps

| Gap | Why it matters |
| --- | --- |
| Untracked Company OS surface | Some docs/config/scripts/components exist locally but are not tracked. Product truth should become committed truth. |
| Paperclip parity | Routine-scoped secret binding, managed worktree reseed, routine engine parity, notification connectors, connector/plugin config UX, and a side-by-side diff view remain incomplete. The unified workspace diff review panel (`/workspace/review`), Command-K search (`app/lib/company-search.ts`), and a first-slice dedicated Company OS MCP server (`services/company-os-mcp-server/`) exist. |

## Latest Live Proof

The new-operator proof passed using the opt-in OpenRouter free lane:

```bash
HSM_OPENROUTER_STACK=1 \
HSM_OPENROUTER_FREE_MODEL='openai/gpt-oss-120b:free' \
HSM_WORKER_FREE_OPENROUTER_MODEL='openai/gpt-oss-120b:free' \
HSM_NEW_OPERATOR_AUTO_UP=1 \
bash scripts/company-os-new-operator-smoke.sh
```

It proved that Company OS can open from a clean local database, create a starter company/task, show runtime optional-lane badges, run agent-chat, and persist `turn_plan`, `artifact_grade`, and `promotion_gate` in the resulting agent run. Report path: `/tmp/hsm-company-os-new-operator-smoke.json`.

## Verification Commands

```bash
bash scripts/company-os-truth.sh
bash -n scripts/company-os-new-operator-smoke.sh
bash -n scripts/company-os-up.sh scripts/company-os-harness.sh scripts/lib/company-os-unified-harness.sh
cd web/company-console && npx tsc --noEmit
bash scripts/cargo-reliable.sh check -p hyper-stigmergy
```

Run the live stack when local prerequisites are ready:

```bash
bash scripts/ollama-pull-chat-model.sh
./company-os
bash scripts/company-os-new-operator-smoke.sh
```

Or use the current OpenRouter free proof lane:

```bash
HSM_OPENROUTER_STACK=1 HSM_NEW_OPERATOR_AUTO_UP=1 bash scripts/company-os-new-operator-smoke.sh
```