Fail-Safes and Boundaries

This document describes what stops OGL Cortex agents from doing damage, what happens when a component fails, and how the system recovers. It covers the three enforcement layers, every guard in the OGL layer, the context and compaction lifecycle, the watchdog set, failure handling per component, and the failure classes each guard defends against.

Related documents: 03-configuration-registry.md covers how hooks are registered. 11-ai-safety-governance.md lists the rules these guards enforce.

Terms

• Hook: a script Claude Code runs at a fixed moment: before a tool call (PreToolUse), after one (PostToolUse), at compaction (PreCompact, PostCompact), at session start (SessionStart), on each prompt (UserPromptSubmit) or at session end (SessionEnd, Stop).
• Block: a PreToolUse hook stops a call only when it exits with code 2. Claude Code treats any other non-zero exit code as a non-blocking error, and the call still runs. Every blocking guard in OGL Cortex exits 2 on purpose. This is the most important fact in this document.
• Pass token: a file the agent touches to let one blocked command through. It is consumed on use and expires after 10 minutes.
• Fail closed / fail open: when the guard itself crashes, "closed" blocks the command and "open" lets it run.
• Seat: one running Claude Code agent with its own folder under $CORTEX_HOME/orgs/<org>/agents/<seat>/.
• Roles: the orchestrator (the seat the owner talks to), specialists (builder, analyst and other workers), the auditor (checks claims and gates installs) and the sentinel (watches machine health).
• Compaction: Claude Code squeezing a long conversation into a summary so it fits the model's context window.

1. Rule enforcement: three layers

Every rule in OGL Cortex is held by one or more of three layers:

1. Mechanical: a hook or wrapper script refuses the action. It works even when the agent forgets the rule.
2. Instruction: the rule is written in CLAUDE.md, GUARDRAILS.md, MEMORY.md or a skill. It works only if the agent reads, remembers and obeys it.
3. Auditor: another party checks after the fact. The auditor seat runs hourly passes, peers log catches in a truth ledger, and the owner approves risky actions.

The design principle is "prefer guards that work when you are wrong about yourself". A rule that fails under instruction alone is a candidate for a mechanical guard.

1.1 Where hooks are registered

Hooks load from two settings scopes. Each scope fences a different set of sessions.

Default guard placement:

Option: a guard registered only in seat settings does not fence a desktop session the owner starts outside the seat folders. To put home-wide cleanups behind the same fences, also register the shared-surface guard in ~/.claude/settings.json and give the owner a personal pass token.

1.2 Mechanical guards

The command-line tool is named cortextos.

Wrapper gates are scripts the agent calls. They are mechanical only when used:

Non-guard hooks shape context and refuse nothing: Telegram relays for permission prompts, plan mode and questions; idle flag and crash alert; compaction meter, state hand-back and summary saver. The memory hooks fit the same slot: the PreCompact checkpoint, session-start injection, session facts, and with flags the session digest and prompt-time recall. Prompt-time routing and a post-commit trigger for harness/tools/adversarial-pass.sh are not included. Keep UserPromptSubmit hooks fast: their run time is added to every prompt.

The shared-surface guard and the Orwell send-lint write logs under $OGL_STATE_DIR (default ~/.ogl-cortex/state/: surface-guard.log, orwell-lint.log). Each line carries a verdict (PASS, BLOCK, WARN, NOTE, shadow, pass-once, FAIL-CLOSED, FAIL-OPEN) and the seat. A guard counts as live only after a real call leaves a line in its log.

1.3 Ship gate requirements

The ship gate is the guard most likely to look stronger than it is. It meets these requirements:

• Exit 2 on block. A hook that prints "BLOCKED" and returns 1 does not stop the command.
• Match every deploy form. vercel --prod, npx vercel --prod --yes and vercel deploy --prod are all production deploys. A pattern that requires the word deploy misses the first two.
• Bind the report to the tree. A pass report in any parent folder with no date check lets any command under that folder through. Require the report to be newer than the last change in the tree being shipped, or route every deploy through harness/tools/ship.sh and block raw vercel.
• Prove it with a sink. Feed the hook a payload that must be refused and check the exit code is 2. A passing selftest does not prove the live hook blocks.
• Never let a wrapper rewrite a verdict. Risk acceptance lives in a separate file. The report always carries the true verdict.

1.4 Shared-surface parser coverage

The shared-surface guard ships with a release process: the builder writes the change, the auditor gates it with a written report, and the install happens only on the auditor's PASS. The parser treats each of these forms as a delete or write, and each is a test row:

The code-analysis rule ships warn-only and flips to block per seat after a 48-hour window with zero false positives. Schedule that readout as a one-shot cron.

1.5 No inline LLM judge

Every PreToolUse guard is deterministic Python. There is no inline LLM judge and no classifier model in the tool path. Model-based checks run after the fact:

• the adversarial pass (harness/tools/adversarial-pass.sh), a fresh read-only Claude session that attacks one claim, never blocking;
• the auditor subagent type, a read-only checker the orchestrator uses before saying "done";
• the auditor seat, a full Claude seat doing hourly audits (1.7).

This keeps the tool path fast and its verdicts reproducible.

1.6 Rules held by instruction only

These rule classes have no hook behind them by default. They hold only if the agent remembers them. Each is a candidate for a guard.

Pass tokens are a speed bump, not an approval. The agent that was blocked can release itself. The value is a forced second step and a log line the auditor reads.

1.7 Rules held by a person or an auditor seat

2. Tokens and context

2.1 Settings

Interaction: with a 1M window and auto-compaction at 430k, the daemon's 80% and 88% thresholds (800k and 880k) are not reached in normal use. The meter plus auto-compaction do the work. The daemon path that still applies is the hard overflow check, which force-restarts a seat when the terminal shows an overflow error and usage corroborates it. If you lower the window or raise autoCompactWindow, recheck which threshold fires first.

2.2 What happens as context fills

2.3 What is lost and how it comes back

Implementation note for checkpoint hooks: a shell hook that runs python3 - << 'EOF' gives Python the script on stdin, so the hook's JSON payload never arrives and transcript_path is empty. The shipped precompact_checkpoint.py is a plain file that reads the payload from stdin first and writes to a dedicated file. When it captures zero messages it writes CHECKPOINT FAILED, the next session start shows a warning, and scripts/doctor.sh reports a FAIL. Prove it with /compact (GETTING-STARTED.md, M1).

2.4 Session rotation and restarts

The daemon restarts each seat after max_session_seconds with --continue, which keeps the conversation. The timer re-reads config.json on each fire, so a changed value takes effect without a daemon restart. After a daemon restart every seat comes back with --continue and re-reads its bootstrap files.

Daemon commands take --instance <instance>. Without it the CLI targets the default instance and can report "Daemon is not running" while your instance is up.

3. Fallback behaviour

3.1 Watchdog set

Run watchdogs that must survive a dead or capped agent session under launchd (or systemd), not as agent crons. Agent-session crons stop when the seat stops.

3.2 Failure by failure

Telegram fails. The send call throws on error and has no retry queue. A 429 rate limit is logged as a warning (src/telegram/api.ts). The poller fetches inbound messages and recovers next tick, so messages wait on Telegram's side. Fallback channels are the Agent Office and the mobile control API. Route every send through cortextos bus send-telegram: raw curl sends never reach outbound-messages.jsonl and leave no record.

The daemon fails. pm2 restarts it. If pm2 cannot be read, the launchd resurrect check pages the orchestrator, then the owner. Restart storms page within 15 s.

An MCP server fails. There is no built-in MCP watchdog. Add a session-start check that names failed MCP servers in the seat heartbeat, and remove dead entries from ~/.claude.json. A stdio server whose command is a URL cannot start. The fallback for the knowledge layer is reading the source notes directly. Shared toolchain caches are a single point of failure: one uv cache prune --force can break every running uvx MCP server at once, which is why the surface guard blocks it.

The dashboard fails. The dashboard is a viewer. The bus, crons and Telegram work without it. Run it as a production build (next build then next start) and add it to the uptime watch if you depend on it.

Google auth fails. The identity check detects a credential file that holds the wrong account and pages once. The account guard then blocks that account in the MCP. Readers use the on-disk token, check the token's email and refuse a mismatch, so alerts exit non-zero instead of reporting a false read.

Hosting billing fails. An uptime watcher cannot see payment state. Track invoices separately.

Disk fills. Alert under 20 GiB, automatic prune of Docker images and build cache under 10 GiB, page at the floor. Nothing deletes agent data on its own. A full disk can corrupt a Docker VM and lose every container and volume, so keep the floor generous.

Swap fills. The sentinel pages at a swap-file threshold. Relief is manual: drop caches inside the Docker VM, restart Docker, stop stray crawls. While swap is high, hold heavy jobs (deploy scans, local browsers, local speech models).

A cron fails. The daemon owns schedules. A missed heartbeat write produces "Cron gap detected" nudges every 10 minutes. Write cron prompts to verify by receipt, never by silence. An interval cron as long as the heartbeat interval never fires, so long jobs use wall-clock five-field schedules (src/bus/crons.ts).

Backups. Decide per database whether it needs running backups. If you disarm backup jobs, keep frozen encrypted dumps and a written restore procedure, and record the decision.

4. Failure classes and the guard for each

Each guard exists to stop a class of failure. This table maps class to defence and says whether the defence is mechanical.

Smaller patterns: cron cannot reach the login keychain, so a sentinel that needs it runs inside the login session; a lint that reads only line 1 of a multi-line send misses the rest; a watcher that stops on one failed account stops on all of them unless it counts failures per account; a gate run from the wrong folder can scan gigabytes.

5. Known limitations

1. Command-text guards do not see what interpreted code (Python, Node, AppleScript, JXA) does at run time, or paths assembled at run time.
2. Pass tokens are self-released. They log; they do not authorise.
3. No guard checks for an approval id before a website deploy.
4. Seats run with --dangerously-skip-permissions, so the permission relay sees few prompts. Approval gates rely on the bus and on instruction.
5. There is no MCP watchdog and no automatic restart of failed MCP servers.
6. Heartbeat rows for parked or retired seats go stale but can still read "online". Prune retired agents from the fleet view.
7. The daemon's idle watchdog heartbeat lands on a row named after the instance rather than the seat if the heartbeat call lacks the seat identity.
8. One-shot crons do not remove themselves unless the prompt does it. Give them an end date or a checked self-remove step.
9. Claude Code cuts auto-memory indexes over 200 lines at load. Keep the index short.
10. Logs grow without bound unless added to a rotation job.
11. The cron store lives under the instance state folder (~/.cortextos/<instance>/.cortextOS/state/agents/<agent>/crons.json). Templates that name ${CTX_ROOT}/state/<agent>/crons.json describe an older layout.

6. Risk table

Likelihood (L) and impact (I) are scored 1 to 5 for a typical single-owner install. Score = L x I. These are judgments.

Design notes

• User-level registration of the surface guard fences every session, including the owner's. Leaving it seat-only keeps owner sessions free and leaves agent evidence open to cleanups.
• A hard ship gate at user level refuses every deploy that lacks a fresh pass. Turn it on knowingly.
• The send-boundary lint closes the variable and heredoc bypass. It changes cortextos bus send-telegram and ships with a test that drives it to fail once.

Source files

• src/daemon/fast-checker.ts
• src/daemon/agent-process.ts
• src/daemon/agent-manager.ts
• src/telegram/api.ts
• src/bus/crons.ts
• src/hooks/hook-context-status.ts
• src/hooks/hook-permission-telegram.ts
• src/hooks/hook-planmode-telegram.ts
• src/hooks/hook-extract-facts.ts
• OGL layer: harness/hooks/shared_surface_guard.py, harness/hooks/surface.py, harness/hooks/codewrites.py, harness/hooks/orwell_lint.py, harness/hooks/brief_guard.py, harness/hooks/future_time_guard.py, harness/hooks/ship_gate.py, harness/hooks/compaction/; tools in harness/tools/