@phigon/observer 8.0.2 → 8.2.0

package/README.md

@@ -1,303 +1,376 @@
-<p align="center">
-  <a href="https://phigon.online">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://phigon.online/brand/phigon-white.svg" />
-      <img src="https://phigon.online/brand/phigon-black.svg" alt="Phigon" width="72" />
-    </picture>
-  </a>
-</p>
-
-# Phigon Observer
-
-Connect your AI coding agents to [Phigon](https://phigon.online), the
-consent-based supervision workspace for authorized AI activity.
-
-Phigon helps you see:
-
-- which approved machines are connected;
-- which AI agents are installed or running;
-- current activity and agent health;
-- saved agent threads and history when sharing is approved.
-
-Phigon is consent-based. The observer starts with privacy-safe metadata only,
-and sensitive activity remains protected unless the machine owner approves it.
-
-## Install and connect
-
-Requires **Node.js 24 or newer** with npm. Releases include Guardian runners for
-Windows, macOS, and Linux on x64 and ARM64. Go is not required to install.
-
-```sh
-npm install --global @phigon/observer
-```
-
-1. Sign in to [Phigon](https://phigon.online) and select **Connect machine**.
-2. Choose **Metadata** or **Full activity**, then generate a one-time code.
-3. Run the pairing and monitoring commands shown in the connection dialog on
-   the machine you administer. The machine owner reviews and accepts the scope.
-
-For metadata-only monitoring:
-
-```sh
-phigon-observer pair --code YOUR-CODE --consent-profile metadata
-phigon-observer run --profile metadata
-```
-
-For supported conversations, commands, outputs, and past-history import, select
-Full activity in Phigon and use the matching profile:
-
-```sh
-phigon-observer pair --code YOUR-CODE --consent-profile full
-phigon-observer run --profile full
-```
-
-`YOUR-CODE` is the one-time code from your workspace. Keep the observer process
-running for live collection. Closing the dashboard does not stop capture;
-stopping the observer does. Full activity still requires matching workspace
-policy and local consent, and secrets are redacted before delivery.
-
-Check installation and connection health with:
-
-```sh
-phigon-observer doctor --json
-```
-
-### Upgrade from the previous npm package
-
-The maintained package is now **`@phigon/observer`**, published under the
-`phigon` npm account. The executable is still **`phigon-observer`**.
-The old unscoped package will not automatically switch to the new package.
-
-Stop your observer process or managed service, then run:
-
-```sh
-npm uninstall --global phigon-observer
-npm install --global @phigon/observer
-phigon-observer doctor --json
-```
-
-Restart with the same collection profile and environment as before. Keep your
-existing Phigon data directory: npm package replacement does not require a new
-pairing or removal of machine credentials. Managed-service installations may
-need their executable path updated to the new global install location. To
-update future releases, run `npm install --global @phigon/observer@latest`.
-
-To monitor an agent that does not have a built-in adapter, register its local
-signals once. Definitions are reloaded on every discovery and activity scan:
-
-```sh
-phigon-observer agent add \
-  --id release-bot \
-  --name "Release Bot" \
-  --executable release-bot \
-  --process release-bot-worker \
-  --config-path ~/.release-bot \
-  --activity-dir ~/.release-bot/sessions
-```
-
-Use `phigon-observer agent list` to inspect the active definitions and
-`phigon-observer agent remove --id release-bot` to stop using one. Custom
-activity remains visibly source-isolated unless independent process-lifetime
-evidence proves one exact match. Activity directories accept bounded JSONL and
-expand `~/` against the current user's home directory. Paths must be absolute
-or home-relative, activity roots must be narrowly scoped, and overlapping
-identity or activity signals are rejected instead of guessed.
-
-To disconnect and unregister the paired machine from that machine itself:
-
-```sh
-phigon-observer remove-machine
-```
-
-The command requires local confirmation, revokes the machine credential, and
-clears it only after the control plane confirms removal. Workspace retention
-and administrator-managed historical data deletion remain separate controls.
-
-Return to [Phigon](https://phigon.online) to view the machine, grouped AI
-agents, live status, health, and available history.
-
-## Past conversations and live capture
-
-When a machine owner pairs with Full activity consent and runs with `--profile
-full`, the observer automatically imports supported past conversations. It
-resumes that import after a restart. Past chats appear directly in Conversations;
-new prompts, replies, and tool activity are captured independently in real time.
-Administrators can request another archive scan through the authenticated
-`POST /v1/machines/{id}/history-syncs` API. A manual scan reports success only
-after the server acknowledges its final event. Only permitted, locally redacted
-source content is collected; private provider-encrypted reasoning is not decoded.
-
-The dashboard does not need to stay open. Normal live monitoring and queued
-history jobs are driven by the observer process. Local state is limited to
-source checkpoints and an encrypted delivery spool; hosted history remains on
-the server and duplicate source records are suppressed across retries.
-
-## Optional agent actions
-
-Remote agent actions are disabled on every machine by default. A machine owner
-may opt in to the typed Action Center executor before starting the observer:
-
-```sh
-PHIGON_REMOTE_ACTIONS_ENABLED=true phigon-observer run
-```
-
-This capability accepts graceful stop and force stop for one exact reported
-agent process lifetime. An operator proposal and separate administrator
-confirmation are required, commands expire quickly, the observer refreshes
-local discovery before signaling, and it persists an idempotent terminal
-receipt. This setting does not enable shell commands, file access, screen or
-camera capture, or general remote control. Windows graceful stop uses
-`taskkill.exe /PID` without the force flag and never silently escalates;
-Unix-like systems use `SIGTERM`. Force stop remains a separately approved
-capability on every supported platform.
-
-To additionally enroll this machine for administrator-reviewed system operations,
-set `PHIGON_REMOTE_COMMANDS_ENABLED=true` before starting the observer. This
-separate capability enables executable/argument commands, current system
-inspection, and scheduled shutdown/restart through Actions and Cortex. Commands
-run as the observer account, require an exact administrator review, expire before
-dispatch, have a 1–120 second limit, and return at most 32 KB of redacted output.
-A durable execution journal prevents retrying a previously claimed command after
-a crash. A power receipt means a one-minute change was scheduled, not that the
-machine already powered off. See [the administration guide](https://github.com/imthegoodboy/Phigon/blob/imp/docs/admin-controls-upgrade.md).
-
-Managed agent integrations can request the hosted fail-closed Guardian decision
-before performing an action:
-
-```sh
-phigon-observer authorize-action \
-  --agent codex:worker-1 \
-  --action command.execute \
-  --resource "git status" \
-  --context-file ./phigon-action-context.json \
-  --json
-```
-
-The optional context file is bounded JSON with `task_id`, `proposal_id`,
-`plan_step_id`, `user_prompt`, `agent_plan`, `justification`,
-`expected_effect`, and `recent_activity` fields. These are explicit integration
-evidence, not private model chain-of-thought. The gateway
-returns exit code 0 only for an allow. A deny, approval requirement, or
-unavailable semantic decision returns exit code 77, together with a message
-for the agent. A deny or approval also carries the exact authoritative
-administrator contract returned by the control plane. Every decision is appended
-to the observer's generic activity bridge so normal background telemetry can
-store it even when the dashboard is closed.
-
-For a running agent, integrations should also pass the discovered
-`--process-id` and `--process-started-at` together. The control plane binds that
-pair to fresh machine inventory before honoring agent-specific scope. Without
-that proof it evaluates conservatively across all potentially relevant
-agent-scoped contracts; a caller-supplied agent label cannot remove a policy.
-
-When a semantic contract requires approval, the hosted control plane creates a
-durable request bound to the exact policy digest, action, resource, contract,
-and evidence envelope. An administrator can approve or reject it in Guardian.
-Retrying the unchanged proposal after approval consumes a single-use grant;
-another execution requires a new `proposal_id`.
-
-For CLI agents, run commands through the managed execution boundary so the
-same pre-action decision is mandatory and command input, streamed output, and
-the final exit are captured by the normal background telemetry pipeline:
-
-```sh
-phigon-observer guardian exec \
-  --agent codex:worker-1 \
-  --context-file ./phigon-action-context.json \
-  -- npm test
-```
-
-To govern the agent product and model before it starts, use the managed agent
-launcher:
-
-```sh
-phigon-observer guardian launch \
-  --agent claude-code:worker-1 \
-  --model anthropic:claude-sonnet-4-5 \
-  --context-file ./phigon-action-context.json \
-  -- claude
-```
-
-The launcher requires an explicit model claim and obtains one short-lived,
-single-use grant covering `agent.start`, `model.use`, and `command.execute`.
-The grant binds the executable and input file hashes, arguments, working
-directory, environment, and current company policy. The native supervisor
-contains the managed process tree and stops it if its online lease cannot renew.
-It renews directly with the control plane, so an observer event-loop stall does
-not disable policy revocation. Its private credential bootstrap is removed before
-the workload starts and is excluded from command arguments and activity journals.
-Pending administrator approval holds the complete launch; any denied or
-unavailable check prevents it from starting.
-`guardian exec` also checks `agent.start` when no model is declared. Before either
-launch mode creates its manifest, it retrieves the company's assigned OS profiles.
-Linux profiles enforce filesystem permissions and optional denial of all sockets
-through Landlock/seccomp; unsupported assigned protections block launch. Profiles
-also support Windows/Linux memory, CPU and process limits, runtime deadlines,
-and Linux workload UID/GID separation when the required protected launcher and
-cgroup are provisioned. macOS currently accepts runtime deadlines only. Profiles
-are checked again during grant consumption and online lease renewal. An all-socket
-deny profile also blocks the loopback model gateway.
-
-Compatible agents receive a temporary loopback model gateway credential and
-provider base URLs. The hosted gateway checks every forwarded model request,
-maps only administrator-approved models, and keeps company provider keys on
-the server. Direct provider traffic requires company network controls.
-
-The executable is launched directly without a shell. A held or blocked action
-never starts and returns exit code 77; an allowed command returns its own exit
-code. Programs launched outside this managed boundary still require their own
-Phigon integration or an operating-system application-control policy. A
-business that must prevent direct executable or API bypass also needs OS/MDM
-application control and a controlled model-provider proxy.
-
-Guardian is centrally managed. `phigon-observer guardian status` reports the
-management authority. Local on/off and containment switches have been removed;
-old `guardian-control.json` files are ignored. Administrator policies alone
-specify the allowed intervention, and the executor verifies the exact process
-lifetime before stopping it.
-
-While `phigon-observer run` is active, discovered running process instances are
-also submitted for periodic central review, including agents started outside
-`guardian launch`. A policy-authorized stop or force-stop is dispatched against
-that exact instance and its receipt enters hosted telemetry. Discovery is
-post-launch detection: it cannot undo activity before discovery or contain
-undetected agents. Block-only policies never become background process kills.
-
-For exact model/agent lists, central decision auditing, and enterprise rollout
-boundaries, see [Guardian runtime](https://github.com/imthegoodboy/Phigon/blob/imp/docs/guardian-runtime.md), the
-[business policy catalog](https://github.com/imthegoodboy/Phigon/blob/imp/docs/enterprise-guard-policies.md), and
-[deployment requirements](https://github.com/imthegoodboy/Phigon/blob/imp/docs/guardian-deployment.md).
-Deployment guidance includes the central Linux profile format and generated
-Windows AppLocker build/review/apply/verify/rollback package. Saving a plain-language
-rule does not automatically install machine-wide application controls.
-
-Building from source requires Node 24+ and Go 1.26. `npm run build` produces the
-current platform's native runner. `npm run build:platforms` adds Windows, Linux,
-and macOS x64/ARM64 binaries before release packaging. Installed releases include
-the runner; endpoint users do not need Go.
-
-Phigon includes optimized support for Codex, Claude Code, Cursor, GitHub
-Copilot, OpenCode, Gemini CLI, and more, while the dynamic registry and custom
-NDJSON bridge support locally authorized custom agents without a code change.
-
-## Troubleshooting
-
-- **Command not found:** ensure npm's global executable directory is on `PATH`,
-  then reopen your terminal.
-- **Expired pairing code:** generate another code in Connect machine and retry.
-- **No conversations:** metadata excludes content. Check the accepted profile,
-  workspace policy, and adapter coverage with `doctor --profile full --json`.
-- **Disconnected machine:** keep the observer running and allow its configured
-  HTTPS and telemetry endpoints. Already delivered history stays on the server;
-  queued permitted activity is retried when connectivity returns.
-- **Unsupported source:** Phigon shows missing or limited evidence. It does not
-  fabricate conversations or decrypt provider-private reasoning.
-
-[Setup guide](https://phigon.online/docs/get-started) ·
-[Documentation](https://phigon.online/docs) ·
-[Report an issue](https://github.com/imthegoodboy/Phigon/issues)
-
-## License
-
-This package is proprietary (`UNLICENSED`). Public npm availability does not
-grant an open-source license.
+<p align="center">
+  <a href="https://phigon.online">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://phigon.online/brand/phigon-white.svg" />
+      <img src="https://phigon.online/brand/phigon-black.svg" alt="Phigon" width="64" />
+    </picture>
+  </a>
+</p>
+
+<h1 align="center">Phigon Observer</h1>
+
+<p align="center">
+  See what AI coding agents do on a computer, with the owner's consent.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@phigon/observer"><img alt="npm" src="https://img.shields.io/npm/v/@phigon/observer?color=000000&label=npm"></a>
+  <a href="LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-000000"></a>
+  <a href="https://github.com/phigonai/observer/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/phigonai/observer/actions/workflows/ci.yml/badge.svg"></a>
+</p>
+
+The Phigon Observer runs on a computer where people use AI coding agents such as
+Claude Code, Codex, Cursor and GitHub Copilot. It finds the agents, records what
+they do within the scope the computer's owner approves, removes secrets on the
+machine, and streams the activity to a [Phigon](https://phigon.online)
+workspace. It can also check your company's Guardian rules before an agent runs
+a risky action.
+
+It is open source under the [Apache License 2.0](LICENSE), so you can read
+exactly what runs on your computers and what leaves them.
+
+- **Consent first.** Nothing is collected until the computer's owner approves
+  the exact scope on that machine.
+- **Metadata by default.** The default profile shares which agents run and the
+  kind of work they do, not prompts, replies, code or terminal output.
+- **Secrets stay on the machine.** Passwords, tokens and API keys are redacted
+  before anything is sent. Local settings can only narrow what is shared.
+- **Survives disconnects.** Activity waits in an encrypted local queue and is
+  delivered, in order and without duplicates, when the connection returns.
+
+## Supported agents
+
+| | Agent | Detected | Activity and history |
+| --- | --- | --- | --- |
+| <img src="https://phigon.online/agents/claude-code.svg" width="20" alt=""> | Claude Code | Yes | Built in |
+| <img src="https://phigon.online/agents/codex.svg" width="20" alt=""> | OpenAI Codex | Yes | Built in |
+| <img src="https://phigon.online/agents/github-copilot.svg" width="20" alt=""> | GitHub Copilot CLI | Yes | Built in |
+| <img src="https://phigon.online/agents/github-copilot.svg" width="20" alt=""> | GitHub Copilot in VS Code (chat and agent mode) | Yes | Built in |
+| <img src="https://phigon.online/agents/opencode.svg" width="20" alt=""> | OpenCode | Yes | Built in |
+| <img src="https://phigon.online/agents/openclaw.svg" width="20" alt=""> | OpenClaw | Yes | Built in |
+| <img src="https://phigon.online/agents/hermes.svg" width="20" alt=""> | Hermes Agent | Yes | Built in |
+| <img src="https://phigon.online/agents/cursor.svg" width="20" alt=""> | Cursor (editor agent and `cursor-agent` CLI) | Yes | Built in |
+| <img src="https://phigon.online/agents/gemini-cli.svg" width="20" alt=""> | Gemini CLI | Yes | Built in |
+| <img src="https://phigon.online/agents/amp.svg" width="20" alt=""> | Amp | Yes | Bridge |
+| <img src="https://phigon.online/agents/goose.svg" width="20" alt=""> | Goose | Yes | Built in |
+| <img src="https://phigon.online/agents/cline.svg" width="20" alt=""> | Cline (CLI and VS Code extension) | Yes | Built in |
+| <img src="https://phigon.online/agents/openhands.svg" width="20" alt=""> | OpenHands | Yes | Bridge |
+| | Kiro | Yes | Built in (chat; agent actions not yet) |
+| | Antigravity | Yes | Not yet (no documented conversation format) |
+| | Trae | Yes | Not yet (its history database is encrypted) |
+| | Zed (its own agent) | Yes | Built in |
+| | Factory Droid | Yes | Built in |
+| | Roo Code | Yes | Built in |
+| | Kilo Code | Yes | Built in |
+| | Aider, Amazon Q Developer CLI, Continue | Yes | Bridge |
+| | Any other agent | [Register it](#custom-agents) | Bridge |
+
+*Built in* means the observer reads the agent's own records. *Bridge* means the
+agent (or a small wrapper) pipes NDJSON to `phigon-observer ingest`.
+
+## How it works
+
+```
+ Your computer                                      Phigon workspace
+┌──────────────────────────────────────────┐       ┌─────────────────────────┐
+│  AI agents  (Claude Code, Codex, ...)     │       │  Control plane          │
+│      │  their own records and processes   │       │   history and search    │
+│      ▼                                    │  TLS  │   Guardian rules        │
+│  phigon-observer                          │ ────► │   the Phigon app        │
+│   discover → collect → redact             │ gRPC  └─────────────────────────┘
+│   → encrypted queue → stream              │
+│                                           │
+│  Guardian runner  (managed launches)      │
+└──────────────────────────────────────────┘
+```
+
+The observer never needs inbound connections. It talks to the control plane
+over HTTPS for pairing and over a single authenticated gRPC stream for
+telemetry. The wire protocol is in [`proto/`](proto).
+
+## Quick start
+
+You need **Node.js 24 or newer** and a Phigon workspace. Installed releases
+include the Guardian runner for Windows, macOS and Linux on x64 and Arm64; Go is
+only needed to build from source.
+
+```sh
+npm install --global @phigon/observer
+```
+
+1. In the Phigon app, choose **Connect machine**.
+2. Choose **Metadata** or **Full activity**, then generate a one-time code.
+3. On the computer, run the two commands the dialog shows. The computer's owner
+   reviews and accepts the scope.
+
+Metadata only:
+
+```sh
+phigon-observer pair --code YOUR-CODE --consent-profile metadata
+phigon-observer run --profile metadata
+```
+
+Full activity (supported conversations, commands, outputs and past history):
+
+```sh
+phigon-observer pair --code YOUR-CODE --consent-profile full
+phigon-observer run --profile full
+```
+
+Keep `phigon-observer run` running for live collection; closing the Phigon app
+does not stop it. Check the installation and connection at any time:
+
+```sh
+phigon-observer doctor --json
+```
+
+## What is collected
+
+What the observer sends is always the overlap of your workspace's policy and
+the profile the computer's owner accepted.
+
+| | Metadata (default) | Full activity |
+| --- | --- | --- |
+| Which agents are installed and running | Yes | Yes |
+| Agent state, health and kind of activity | Yes | Yes |
+| Prompts and replies | No | Supported agents |
+| Commands, tool calls and their output | No | Supported agents, redacted |
+| Past conversations | No | Imported once, then live |
+| Passwords, tokens and API keys | Never | Never (redacted on the machine) |
+| Provider-encrypted model reasoning | Never | Never decoded |
+
+Individual categories can be narrowed further with `PHIGON_COLLECT_*`
+settings. A full description is in
+[privacy and security](https://phigon.online/docs/privacy-and-security/).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `pair --code <code> --consent-profile <metadata\|full>` | Connects this computer to a workspace after local consent. |
+| `run [--profile <metadata\|full>]` | Discovers agents and streams permitted activity. |
+| `doctor [--profile <...>] [--json]` | Checks the setup without sending any data. |
+| `discover [--json]` | Prints a one-time, sanitized inventory of local agents. |
+| `agent add \| list \| remove` | Manages custom agent definitions. |
+| `ingest --agent <id\|custom> [--name <name>]` | Reads NDJSON activity from stdin (bridges). |
+| `guardian status \| exec \| launch` | Guardian checks and managed execution. |
+| `authorize-action --action <a> --resource <r>` | Asks Guardian whether one action may run. |
+| `update [--check] [--yes]` | Checks for or installs a new release. |
+| `remove-machine` | Unregisters this computer and revokes its credential. |
+
+Run `phigon-observer help` for every flag.
+
+### A company's own Phigon server
+
+The Phigon app can run a company's own server, and other computers on the
+company network can connect to it. That server signs its HTTPS certificate
+with an authority of its own, so the **Connect machine** command adds
+`--server-ca-sha256 <fingerprint>`.
+
+On first contact, pairing finds the authority in the server's certificate
+chain whose SHA-256 matches the fingerprint. It saves that authority as
+`server-ca.pem` in the data directory, and every later HTTPS and gRPC
+connection trusts it. A server that presents another certificate is refused
+before anything is sent. `remove-machine` deletes the file. This needs
+Node.js 24.5 or newer.
+
+## Configuration
+
+Settings are environment variables. The most common ones:
+
+| Variable | Purpose |
+| --- | --- |
+| `PHIGON_DATA_DIR` | Where the credential, checkpoints and encrypted queue live. Use a separate directory per workspace. |
+| `PHIGON_CONTROL_PLANE_URL`, `PHIGON_GRPC_URL` | Endpoints for a self-hosted workspace. Pairing saves them; the stream refuses to send credentials anywhere else. |
+| `PHIGON_TLS_CA_FILE` | A private certificate authority for gRPC. Use `NODE_EXTRA_CA_CERTS` for HTTPS. Pairing with `--server-ca-sha256` sets up both for you. |
+| `PHIGON_TLS_CLIENT_CERT_FILE`, `PHIGON_TLS_CLIENT_KEY_FILE` | Client certificate, when the workspace requires mutual TLS. |
+| `PHIGON_COLLECT_*` | Turns individual content categories off (or on, within the workspace policy). |
+| `PHIGON_REDACT_PATH_PATTERNS` | Extra file path patterns to redact. |
+| `PHIGON_<AGENT>_ACTIVITY_DIRS` | Extra record folders for an agent, e.g. `PHIGON_CLAUDE_ACTIVITY_DIRS`. |
+| `PHIGON_REMOTE_ACTIONS_ENABLED` | Opt in to administrator-approved agent stop and force stop. Off by default. |
+| `PHIGON_REMOTE_COMMANDS_ENABLED` | Opt in to administrator-reviewed system operations. Off by default. |
+| `PHIGON_USER_NOTICES` | Set to `false` to stop telling the person at the computer when Phigon stops an agent, runs a command or restarts it. On by default. |
+| `PHIGON_UPDATE_CHECK` | Set to `false` to turn off the once-a-day update check. |
+| `PHIGON_LOG_LEVEL` | Logging detail. |
+
+Never disable certificate verification. Interactive `pair` and `run` sessions
+check npm for a new release at most once a day and ask before updating;
+background services and `--json` commands never prompt or update on their own.
+
+## Custom agents
+
+To monitor an agent without a built-in adapter, register its local signals once:
+
+```sh
+phigon-observer agent add \
+  --id release-bot \
+  --name "Release Bot" \
+  --executable release-bot \
+  --process release-bot-worker \
+  --config-path ~/.release-bot \
+  --activity-dir ~/.release-bot/sessions
+```
+
+Definitions are reloaded on every scan. `agent list` shows them and
+`agent remove --id release-bot` stops using one. Activity directories accept
+bounded JSONL; paths must be absolute or start with `~/`, roots must be narrow,
+and overlapping signals are rejected instead of guessed. Custom activity stays
+labeled by its source unless independent process evidence proves an exact
+match.
+
+## Optional agent actions
+
+Remote actions are off on every computer by default.
+
+- `PHIGON_REMOTE_ACTIONS_ENABLED=true` lets administrators stop or force-stop
+  one exact running agent process. Each stop needs an operator proposal and a
+  separate administrator confirmation, expires quickly, and leaves a receipt.
+  A stop acts on one exact process lifetime (process ID plus start time, checked
+  again just before anything is sent) and the child processes it started.
+  Graceful stop sends `SIGTERM` on Linux and macOS; on Windows it asks the
+  agent's windows to close, and for a console agent it presses Ctrl+C in its
+  terminal, but only when nothing else shares that terminal; otherwise it
+  sends nothing and reports `terminal_shared`.
+  Force stop is approved separately. Receipts say when the process had already
+  exited, access was denied, or the agent or a child is still running. It does
+  not enable shell access, file access, screen capture or general remote
+  control.
+- `PHIGON_REMOTE_COMMANDS_ENABLED=true` additionally allows
+  administrator-reviewed commands (executable and arguments, no shell), system
+  inspection, and scheduled shutdown or restart. Commands run as the observer's
+  account, are limited to 1–120 seconds and return at most 32 KB of redacted
+  output. A durable journal prevents a command from running twice after a crash.
+  System inspection reports the operating system, memory, uptime, CPU load,
+  space on the main drive, the observer version, and each running agent's
+  name, process ID, CPU share, memory and run time, measured once over half a
+  second. It never includes file contents, environment values or command lines.
+
+Whenever Phigon stops an agent on a computer, whether someone asked, Phigon AI
+decided or the agent is blocked, the person at that computer sees a system
+notification such as "Claude Code was stopped by Phigon", with the reason. The
+same goes for commands Phigon runs and a scheduled restart or shutdown. It uses
+the system's own notifications (a Windows toast, macOS Notification Center, or
+`notify-send` on Linux) and shows nothing when the observer runs without a
+desktop session, for example as a Windows service. `PHIGON_USER_NOTICES=false`
+turns it off.
+
+## Guardian: checks before an agent acts
+
+Guardian rules are set centrally by your administrators; the observer has no
+local on/off switch. Three integration points are available.
+
+**Ask before one action.** Returns exit code `0` only when the action is
+allowed; a denial, a required approval or an unavailable decision returns `77`
+with a message for the agent:
+
+```sh
+phigon-observer authorize-action \
+  --agent codex:worker-1 \
+  --action command.execute \
+  --resource "git status" \
+  --context-file ./phigon-action-context.json \
+  --json
+```
+
+The optional context file holds bounded `task_id`, `proposal_id`,
+`plan_step_id`, `user_prompt`, `agent_plan`, `justification`,
+`expected_effect` and `recent_activity` fields. Pass `--process-id` and
+`--process-started-at` for a running agent so the decision is bound to that
+exact process.
+
+**Run a command through Guardian.** The check is mandatory, and the input,
+output and exit code are recorded:
+
+```sh
+phigon-observer guardian exec --agent codex:worker-1 -- npm test
+```
+
+**Launch an agent through Guardian.** One short-lived grant covers starting the
+agent, using the declared model and running the command. The Guardian runner
+contains the process tree, renews its lease directly with the control plane and
+stops the agent if the lease is revoked:
+
+```sh
+phigon-observer guardian launch \
+  --agent claude-code:worker-1 \
+  --model anthropic:claude-sonnet-4-5 \
+  -- claude
+```
+
+Assigned OS profiles are enforced at launch: on Linux, filesystem and network
+rules through Landlock and seccomp, plus memory, CPU and process limits and
+separate workload users when a cgroup is provisioned; on Windows, memory, CPU
+and process limits; on macOS, runtime deadlines. Compatible agents receive a
+temporary loopback model gateway, so company provider keys stay on the server.
+
+While `run` is active, running agents are also reviewed periodically, including
+ones started outside `guardian launch`. Discovery happens after launch, so it
+cannot undo earlier activity. A company that must prevent bypass also needs
+operating-system application control and a controlled model provider proxy.
+
+## Troubleshooting
+
+- **Command not found:** put npm's global bin directory on `PATH` and reopen
+  the terminal.
+- **Expired pairing code:** generate a new one in **Connect machine**.
+- **No conversations:** the metadata profile excludes content. Check with
+  `phigon-observer doctor --profile full --json`.
+- **Disconnected:** keep `run` running and allow its HTTPS and gRPC endpoints.
+  Queued activity is delivered when the connection returns.
+- **Older self-hosted pairing without a saved stream endpoint:** pass
+  `run --grpc-url https://stream.your-company.example` or set `PHIGON_GRPC_URL`.
+- **Unreadable pairing data:** keep the data directory and encrypted queue, and
+  restore the credential file from a trusted backup. Never paste it into a
+  support message.
+
+More help: [setup guide](https://phigon.online/docs/get-started/),
+[documentation](https://phigon.online/docs/) and
+[troubleshooting](https://phigon.online/docs/troubleshooting/).
+
+## Building from source
+
+You need Node.js 24+ and Go 1.26+.
+
+```sh
+npm ci
+npm run build              # TypeScript and the Guardian runner for this platform
+npm run check              # lint, type check and tests
+npm run build:platforms    # Guardian runners for every platform, for releases
+cd go && go test ./...     # Go tests
+```
+
+After changing the protocol in `proto/`, regenerate the code with
+[Buf](https://buf.build) and record the new checksums:
+
+```sh
+buf generate
+sh scripts/check-generated.sh
+```
+
+### Repository layout
+
+| Path | Contents |
+| --- | --- |
+| `src/` | The observer CLI (TypeScript): discovery, activity adapters, redaction, pairing, the stream client and Guardian integration. |
+| `test/` | Tests for the CLI. |
+| `go/` | Go module `github.com/phigonai/observer/go`: the Guardian runner, the Linux supervisor, OS sandbox profiles, and the generated protocol code. |
+| `proto/` | The wire protocol between the observer and a Phigon control plane. |
+| `scripts/` | Build, install and release helpers. |
+
+## Contributing
+
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) first. This
+repository is published from Phigon's main repository; a maintainer applies
+accepted pull requests there, keeping you as the author, and they appear here
+automatically.
+
+## Security
+
+Please report vulnerabilities privately. See [SECURITY.md](SECURITY.md).
+
+## License
+
+Licensed under the [Apache License, Version 2.0](LICENSE). See [NOTICE](NOTICE)
+and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). The Phigon name and logo
+are trademarks and are not covered by the license; see
+[TRADEMARKS.md](TRADEMARKS.md).