@occasiolabs/occasio 0.8.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,10 @@
+LocalFirst
+Copyright 2026 Leonard Brauer
+
+This product includes software developed by the LocalFirst project
+(https://github.com/occasio-ai/occasio).
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Versions 0.6.6 and earlier of LocalFirst were released under the MIT License
+and remain available under MIT in perpetuity for those releases.

package/README.md

@@ -0,0 +1,216 @@
+# Occasio
+
+> Cryptographically verifiable behavioral attestation for AI coding agents.
+
+When an AI agent writes code in your CI, the question a reviewer or auditor will ask is not *"what did it produce"* — it is *"what did it actually do"*. Which files did it read. Which it was blocked from reading. Which secrets it tried to leak. Which policy was in effect. Whether that record can be trusted six months later.
+
+Occasio sits between the agent and the cloud on your own machine, decides every tool call against one human-readable policy, writes a tamper-evident audit chain of every decision, and produces signed attestations that a third party can verify offline using only `cosign` or a 200-line Python script.
+
+```bash
+npm install -g @occasiolabs/occasio
+
+occasio demo attest      # End-to-end attestation pipeline (30s, no API key)
+occasio demo anomalies   # Live EDR detection on a synthetic adversarial chain (5s)
+occasio harness          # Real Claude Code attacking a denied path — defense holds
+```
+
+The first two demos run against synthetic data so you can see the full pipeline in under a minute with no external dependencies. The third spawns a real Claude Code subordinate under your Anthropic login (bundled auth — no API key required) and proves the defense end-to-end.
+
+---
+
+## What it does, in four layers
+
+**Layer 1 — Tool-call interception.** A local proxy sits between the agent and the Anthropic API. `Read`, `Glob`, `Grep`, `TodoRead`/`TodoWrite`, and a curated set of read-only shell commands (`cat`, `head`, `git status`, `git log --oneline -N`, `ls`, `find`) run in-process on your machine. The file bytes never enter the outbound request.
+
+**Layer 2 — Policy enforcement.** Every tool call hits one decision: `LOCAL` / `PASS` / `BLOCK` / `TRANSFORM`, driven by [`policy.yml`](policy-templates/dev-default.yml). `deny_paths` is enforced on the realpath-resolved absolute path so symlinks and traversal variants resolve to the same denial. `block_secrets_in_tool_results` redacts API keys and JWTs out of any tool output before it re-enters the prompt. Hot-reload: edits to `policy.yml` take effect on the next call, with a `policy_loaded` row written to the audit chain.
+
+**Layer 3 — Behavioral attestation.** `occasio attest --run-id <uuid>` produces a self-contained JSON predicate that commits to the full audit-chain slice for one agent session: every tool call, every block, every transform, every redacted secret, plus the active policy's SHA-256 hash and rules digest. `--sign` wraps it in an [in-toto Statement v1](https://github.com/in-toto/attestation) and Sigstore-signs it using GitHub Actions OIDC (no key management). The predicate type URI is [`agent-attestation/v1`](spec/agent-attestation/v1/README.md). Two independent reference verifiers ship — Node (`occasio attest verify`) and Python ([`docs/attest_verify.py`](docs/attest_verify.py)) — and the test suite asserts they agree byte-for-byte on the same payload.
+
+**Layer 4 — Anomaly detection (EDR).** `occasio anomalies` runs four detectors over a time window of the audit chain: deny-rate spike, file-read-volume burst, previously-unseen tool-input shape, secret-redaction-rate spike. Severity escalates against your historical baseline — a ×500 deviation from normal triggers HIGH; see [`docs/edr-demo.md`](docs/edr-demo.md) for the reproducible defense-in-depth walkthrough.
+
+---
+
+## Why now
+
+Three regulatory drivers, all converging on the same requirement: **runtime evidence of AI-agent behavior must be cryptographically verifiable.**
+
+- **EU AI Act Art. 12** mandates comprehensive automated logging of high-risk AI systems. In effect from 2026 for regulated sectors.
+- **NIST AI RMF (GOVERN, MEASURE, MANAGE families)** is becoming required in US Federal procurement and is influencing FedRAMP AI controls.
+- **SOC 2 Common Criteria** are extending to AI-agent controls — auditors at major firms started asking "show me the agent's tool-call log" in 2026 audits.
+
+There is currently no off-the-shelf product producing a signed, third-party-verifiable artifact for what an AI coding agent did inside your CI. Occasio fills that gap with an open schema (Apache-2.0) and ships the reference implementations for it.
+
+---
+
+## Quickstart
+
+Requires Node.js ≥ 18. Works on Windows, macOS, Linux.
+
+```bash
+npm install -g @occasiolabs/occasio   # Install
+occasio doctor                          # Verify setup (Node, claude CLI, port, profile)
+occasio policy init                     # Write ~/.occasio/policy.yml (dev-default)
+occasio register                        # Add 'claude' shell alias (one-time)
+claude "read package.json and tell me the version"
+```
+
+After the alias is registered, every `claude` invocation routes through Occasio transparently. Audit-chain rows accumulate at `~/.occasio/pipeline-events.jsonl`.
+
+**Inspect the run:**
+
+```bash
+occasio status                  # Session totals
+occasio replay --detail         # Run-level audit
+occasio audit verify            # Re-walk the hash chain end-to-end
+occasio anomalies               # Run EDR detectors over the last 15 minutes
+occasio attest --run-id <uuid>  # Build a behavioral attestation for one session
+```
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `occasio claude [args]` | Start Claude Code with Occasio proxy active |
+| `occasio register` | Register `claude` shell alias |
+| `occasio doctor` | Setup health-check |
+| `occasio status` | Session totals + savings breakdown |
+| `occasio replay` | Run-level audit (`--detail`, `--run <id>`, `--attribute`) |
+| `occasio inspect` | Per-request cloud-boundary manifest |
+| `occasio boundary` | Three-column view: produced / re-entered / prevented |
+| `occasio ledger` | Per-request token ledger |
+| `occasio distill` | Inspect distilled tool outputs |
+| `occasio dashboard` | Live browser dashboard at http://localhost:3001 |
+| `occasio audit verify` | Re-walk the SHA-256 audit chain end-to-end |
+| `occasio report` | Governance summary export (`--days N`, `--format csv`) |
+| `occasio anomalies` | EDR detection over the audit chain (`--window 15m`, `--json`) |
+| `occasio attest --run-id <uuid>` | Build a behavioral attestation predicate v1 |
+| `occasio attest --sign` | Sigstore-sign via GitHub Actions OIDC |
+| `occasio attest verify <file>` | Re-verify a signed attestation end-to-end |
+| `occasio policy [show \| validate \| init \| doctor]` | Policy authoring + diagnosis |
+| `occasio harness` | Run scripted adversarial scenarios against your policy |
+| `occasio redteam` | Autonomous tester-LLM probes a subject Claude Code session |
+| `occasio computer-use --dry-run` | Apply a Computer-Use policy to synthetic tool_use blocks |
+| `occasio demo attest` | End-to-end attestation pipeline against a synthetic chain |
+| `occasio demo anomalies` | EDR smoke test: synthetic adversarial chain → all 4 detectors |
+| `occasio selftest` | In-process governance self-checks on a scratch chain |
+| `occasio baseline [learn \| compare]` | Per-project behavior baseline + drift detection |
+| `occasio preflight` | Read-only mine of recent activity for policy suggestions |
+
+Session-level overrides on top of `policy.yml`:
+
+| Flag | Effect |
+|---|---|
+| `--preset strict` | Forces `block_secrets_in_tool_results` on for the session |
+| `--preset off` | Pure passthrough, log only |
+| `--budget <N>` | Hard cap: HTTP 402 once session cost reaches $N |
+| `--hardened` | Routes Read/Glob/Grep through unified runtime + distill + secret scan |
+
+---
+
+## Verification
+
+Three independent checks, all required for a verified attestation:
+
+1. **Sigstore signature** — Fulcio certificate chain + Rekor inclusion proof. Verifiable by any sigstore-conformant tool (`cosign verify-blob`, `sigstore-js`, `sigstore-python`).
+2. **DSSE payload ↔ attestation predicate equivalence** — re-decode the in-toto Statement inside the bundle, canonicalise the predicate via [RFC 8785 subset](src/attest/canonicalize.js), compare byte-for-byte with the attestation predicate (minus the `signature` metadata field).
+3. **Audit chain integrity** — SHA-256-walk every `prev_hash → hash` link from the GENESIS sentinel, then assert the attestation's `first_hash` and `last_hash` appear in the chain in the right relative order.
+
+Two reference verifiers ship side by side:
+
+- **Node**: `occasio attest verify <file>`
+- **Python**: `python docs/attest_verify.py <file>` — stdlib + optional `sigstore-python`, reuses [`docs/audit_walker.py`](docs/audit_walker.py) for the chain step. See [`docs/python-verifier.md`](docs/python-verifier.md).
+
+**Cross-language invariant** (asserted in the test suite as `xlang:` and `xlang-float:` cases): both verifiers agree byte-for-byte on the predicate-equivalence and audit-chain steps for the same payload, including tamper-detection cases. Non-integer numbers are rejected by both canonicalize implementations so a future schema cannot silently introduce divergence.
+
+The **Sigstore signature step** uses the standard DSSE-wrapped in-toto Statement format; any sigstore-conformant tool verifies it (`cosign verify-blob`, `sigstore-js`, `sigstore-python`). The test suite mocks the signing path; a real-OIDC end-to-end signed-and-verified round-trip requires a GitHub Actions environment and is exercised by the [`integrations/attest-action/`](integrations/attest-action/) workflow in CI.
+
+A third partial verifier runs in-browser at [`integrations/attest-view/`](integrations/attest-view/) for drag-and-drop inspection. The browser performs the predicate-equivalence and audit-chain steps but defers Sigstore certificate-chain verification to one of the two CLIs (bundling Fulcio/Rekor trust roots in-browser is intentionally not done; the page is explicit about it).
+
+---
+
+## Architecture
+
+```
+agent (Claude Code / Cline / MCP / Computer Use)
+  │
+  ▼  tool call
+┌──────────────────────────────────────────────────────────────┐
+│  Occasio proxy                                            │
+│                                                              │
+│  Layer 1: adapter parse → canonical event                    │
+│  Layer 2: policy decision (LOCAL / PASS / BLOCK / TRANSFORM) │
+│  Layer 2: deny_paths + deny_patterns + secret redaction      │
+│  Layer 2: native dispatch for LOCAL/TRANSFORM tools          │
+│           ──► row appended, SHA-256-chained                  │
+│  Layer 4: anomaly detectors (windowed, on-demand or live)    │
+└──────────────────────────────────────────────────────────────┘
+  │
+  ▼  cloud-bound: only PASS calls, with shaped result if TRANSFORM
+Anthropic API
+
+End of session
+  │
+  ▼  occasio attest --run-id … --sign
+Layer 3: signed in-toto Statement → Sigstore bundle → GitHub Check Run
+  │
+  ▼  independent verifier
+Node / Python / cosign — all must agree
+```
+
+---
+
+## Log format
+
+All data is stored locally at `~/.occasio/`:
+
+```
+~/.occasio/
+  pipeline-events.jsonl        # tamper-evident audit chain (SHA-256 linked)
+  policy.yml                   # active policy
+  session.json                 # current run_id, totals
+  logs/YYYY-MM-DD.jsonl        # per-request log
+  baseline/<cwd-hash>.json     # per-project behavior baseline (opt-in)
+```
+
+The audit-chain row schema is documented in [`docs/AUDIT.md`](docs/AUDIT.md). Each row carries `prev_hash` and `hash` (SHA-256 hex), with the first row chained from a fixed GENESIS sentinel (64 zeros). `occasio audit verify` and `docs/audit_walker.py` are independent implementations of the walker.
+
+---
+
+## Demos
+
+- [**EDR defense-in-depth**](docs/edr-demo.md) — real Claude Code attacking a denied path under your policy, all blocks held, EDR fires HIGH ×100–×1000 over baseline. Reproducible in <2 minutes.
+- [**Reference Pipeline**](docs/reference-pipeline.md) — PR with AI-agent → GitHub Action signs attestation via Sigstore keyless → Check Run on the PR → independent verification offline.
+- [**Cross-protocol governance**](docs/demos/mcp-block.md) — the same `deny_paths` rule producing identical `BLOCK` rows under Claude Code's HTTP proxy and the MCP server.
+
+---
+
+## Reference
+
+- [`spec/agent-attestation/v1/README.md`](spec/agent-attestation/v1/README.md) — predicate type specification
+- [`schemas/agent-attestation-v1.json`](schemas/agent-attestation-v1.json) — authoritative JSON Schema
+- [`docs/AUDIT.md`](docs/AUDIT.md) — audit-chain row schema and canonical-serialisation rules
+- [`docs/compliance-mapping.md`](docs/compliance-mapping.md) — SOC 2 Common-Criteria mapping
+- [`docs/python-verifier.md`](docs/python-verifier.md) — independent Python verifier
+- [`docs/edr-demo.md`](docs/edr-demo.md) — defense-in-depth walkthrough
+- [`docs/reference-pipeline.md`](docs/reference-pipeline.md) — end-to-end CI pipeline
+- [`integrations/attest-action/`](integrations/attest-action/) — GitHub Action that signs + posts a Check Run
+- [`integrations/attest-view/`](integrations/attest-view/) — static browser viewer for attestation files
+
+---
+
+## Requirements
+
+- **Node.js ≥ 18**
+- **Claude Code** (`npm install -g @anthropic-ai/claude-code`) — or any agent that respects `ANTHROPIC_BASE_URL`
+- **Python 3** (optional) — required for the independent verifier and LAO context trimming
+- **`sigstore-python`** (optional) — adds the cryptographic Sigstore step to the Python verifier
+
+---
+
+## License
+
+Occasio is open source under the [Apache License 2.0](LICENSE), including an explicit patent grant for safe enterprise use. Versions 0.6.6 and earlier were released under the MIT License and remain MIT in perpetuity for those releases.
+
+Contributions are accepted under Apache-2.0; please sign off your commits per the [DCO](https://developercertificate.org/) (`git commit -s`).

package/bin/occasio-mcp.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+// Entry point for the Occasio MCP server.
+// Registered in .claude/settings.json — Claude Code starts this as a subprocess.
+require('../src/mcp-server');

package/bin/occasio.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/index.js');

package/bin/supervisor/README.md

@@ -0,0 +1,90 @@
+# Occasio supervisor templates (v0.6.4)
+
+Occasio aborts with exit code 1 when it cannot append to its audit log
+(`~/.occasio/pipeline-events.jsonl`). This is intentional — a missing
+audit row must not coexist with a successful tool dispatch. To keep the
+proxy available, pair it with a small supervisor that respawns it on exit.
+The templates below are starting points, not a daemon we ship.
+
+## Validation status
+
+| Template | Platform | Status |
+|---|---|---|
+| `install-windows-task.ps1` | Windows 11 / PowerShell 7+ | **manually validated** |
+| `occasio.service` | Linux / systemd | shipped, **not yet manually validated** by maintainers |
+| `com.occasio.proxy.plist.template` | macOS / launchd | shipped, **not yet manually validated** by maintainers |
+
+The Linux and macOS templates are structurally analogous to the Windows
+one and use standard mechanisms; please open an issue if you hit a
+problem so we can fix the template rather than letting each pilot
+re-derive it.
+
+## Linux (systemd, user scope)
+
+```sh
+mkdir -p ~/.config/systemd/user
+cp occasio.service ~/.config/systemd/user/occasio.service
+systemctl --user daemon-reload
+systemctl --user enable --now occasio
+systemctl --user status occasio
+```
+
+To remove:
+
+```sh
+systemctl --user disable --now occasio
+rm ~/.config/systemd/user/occasio.service
+```
+
+## macOS (launchd, user scope)
+
+The plist is a template: replace `{{LOCALFIRST_BIN}}` with the absolute
+path to your `occasio` binary first.
+
+```sh
+LF_BIN="$(command -v occasio)"
+sed "s|{{LOCALFIRST_BIN}}|$LF_BIN|g" com.occasio.proxy.plist.template \
+  > ~/Library/LaunchAgents/ai.occasio.proxy.plist
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.occasio.proxy.plist
+launchctl print gui/$(id -u)/ai.occasio.proxy
+```
+
+To remove:
+
+```sh
+launchctl bootout gui/$(id -u)/ai.occasio.proxy
+rm ~/Library/LaunchAgents/ai.occasio.proxy.plist
+```
+
+## Windows (Scheduled Task, user scope)
+
+From a PowerShell prompt in this directory:
+
+```pwsh
+pwsh ./install-windows-task.ps1
+```
+
+This registers a task named `Occasio` that runs `occasio start` at
+each logon and restarts the process within one minute if it exits.
+(Windows Scheduled Tasks enforce a one-minute minimum on restart
+intervals; if your threat model requires faster recovery, run a
+foreground supervisor instead.) The
+task scope is the current user; Occasio's audit log is per-user, so
+there is no benefit to running it as SYSTEM.
+
+To remove:
+
+```pwsh
+Unregister-ScheduledTask -TaskName Occasio -Confirm:$false
+```
+
+## Notes
+
+- These templates supervise the proxy process. They do **not** verify
+  the proxy is healthy beyond "the process exists." Pair with an
+  external health-check (`curl http://127.0.0.1:<port>/healthz`) if your
+  threat model requires it.
+- The audit log itself is the source of truth for what was governed
+  while the proxy was running. Gaps in the log (sessions that started
+  with no rows) are a signal that the proxy was not running, not that
+  governance was bypassed silently.

package/bin/supervisor/com.occasio.proxy.plist.template

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  LocalFirst launchd template (v0.6.4).
+
+  This file is a TEMPLATE: replace {{LOCALFIRST_BIN}} with the absolute
+  path to your `occasio` executable before installing. See
+  bin/supervisor/README.md for the install command.
+
+  STATUS: shipped unvalidated on macOS in v0.6.4. The Linux systemd unit
+  is structurally analogous but only the Windows scheduled-task path has
+  been live-tested by the maintainers. Please report issues.
+-->
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>ai.occasio.proxy</string>
+
+    <key>ProgramArguments</key>
+    <array>
+        <string>{{LOCALFIRST_BIN}}</string>
+        <string>start</string>
+    </array>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>/tmp/occasio.out.log</string>
+    <key>StandardErrorPath</key>
+    <string>/tmp/occasio.err.log</string>
+</dict>
+</plist>

package/bin/supervisor/install-windows-task.ps1

@@ -0,0 +1,48 @@
+<#
+.SYNOPSIS
+  Register a Windows Scheduled Task that keeps `occasio` running for
+  the current user, restarting it within 30 seconds if it exits.
+
+.DESCRIPTION
+  v0.6.4 of LocalFirst aborts with exit code 1 when it cannot append to
+  its audit log. This task brings the proxy back up so the agent can
+  resume work as soon as the underlying I/O issue clears.
+
+.NOTES
+  Manually validated on Windows 11 Pro (PowerShell 7.x).
+  Tested-on: Windows.
+
+  The task runs at user logon, not at boot, because LocalFirst's audit
+  log lives in the user profile (~/.occasio/). Run from an elevated
+  shell only if you need the task to survive logoff.
+#>
+
+$Action  = New-ScheduledTaskAction  -Execute "occasio" -Argument "start"
+$Trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
+
+$Settings = New-ScheduledTaskSettingsSet `
+    -RestartCount 999 `
+    -RestartInterval (New-TimeSpan -Minutes 1) `
+    -AllowStartIfOnBatteries `
+    -DontStopIfGoingOnBatteries `
+    -StartWhenAvailable
+
+# -User <current user> + -RunLevel Limited keeps the task in the user
+# scope so Register-ScheduledTask does not require an elevated shell.
+$Principal = New-ScheduledTaskPrincipal `
+    -UserId    $env:USERNAME `
+    -LogonType Interactive `
+    -RunLevel  Limited
+
+Register-ScheduledTask `
+    -TaskName    "LocalFirst" `
+    -Description "LocalFirst — local AI-agent governance proxy (v0.6.4)" `
+    -Action      $Action `
+    -Trigger     $Trigger `
+    -Settings    $Settings `
+    -Principal   $Principal `
+    -Force
+
+Write-Host "Registered scheduled task 'LocalFirst'."
+Write-Host "It will start at next logon. To start now: Start-ScheduledTask -TaskName LocalFirst"
+Write-Host "To remove: Unregister-ScheduledTask -TaskName LocalFirst -Confirm:`$false"

package/bin/supervisor/occasio.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=LocalFirst — local AI-agent governance proxy
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/env occasio start
+Restart=always
+RestartSec=2
+# v0.6.4: the proxy aborts with exit code 1 if it cannot append to its
+# audit log. Restart=always plus a short RestartSec lets the chain resume
+# as soon as the underlying I/O issue clears.
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target