chore(harness): bootstrap Systemfsoftware agent harness and strategy

.github/workflows/ci.yaml

@@ -52,14 +52,23 @@ jobs:
           done
 
           pnpm exec lefthook run pre-commit --no-stage-fixed --fail-on-changes "${args[@]}"
-      - run: npm install -g tsx
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: v2.x
       - name: Run checks
-        run: ./scripts/release/main.ts --version 0.0.0 --only-steps run-ci-checks
+        run: pnpm check:ci
       - name: Run ACP v1 server tests
         run: |
           cargo test -p sandbox-agent-agent-management
           cargo test -p sandbox-agent --test v1_api
           cargo test -p sandbox-agent --test v1_agent_process_matrix
           cargo test -p sandbox-agent --lib
+      - name: Free disk for docker image export
+        run: |
+          df -h /
+          docker system df
+          rm -rf target
+          docker image prune -f
+          df -h /
       - name: Run SDK tests
         run: pnpm --dir sdks/typescript test

.github/workflows/claude-code-review.yml

@@ -36,10 +36,17 @@ jobs:
         with:
           node-version: "20"
 
+      - name: Detect review credentials
+        id: creds
+        run: echo "has_token=${{ secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }}" >> "$GITHUB_OUTPUT"
+
       - name: Install sandbox-agent skill
+        if: steps.creds.outputs.has_token == 'true'
+        continue-on-error: true
         run: npx skills add rivet-dev/skills -s sandbox-agent --yes
 
       - name: Run Claude Code Review
+        if: steps.creds.outputs.has_token == 'true'
         id: claude-review
         uses: anthropics/claude-code-action@v1
         with:
@@ -49,4 +56,3 @@ jobs:
           prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options
-

AGENTS.md

@@ -0,0 +1,58 @@
+# Instructions
+
+Single source of agent law for this repository. Every `CLAUDE.md` in this repo is a one-line pointer to the `AGENTS.md` beside it; never duplicate content between them.
+
+## Naming
+
+- Product display name: **Systemfsoftware**. Components keep their names: `sandbox-agent`, `foundry`, `gigacode`.
+- Org: `systemfsoftware`. npm scope: `@systemfsoftware/*`. Crates keep component names (`sandbox-agent`, ...).
+- Domain: `sandboxagent.systemfsoftware.com`. Do not add new `sandboxagent.dev` references (migration in progress).
+- ACP extension method prefix stays `_sandboxagent/...` for wire compatibility; extension namespace string is `sandboxagent.systemfsoftware.com`.
+- Foundry is the canonical name for the `foundry/` product tree; no pre-Foundry naming.
+- If the user asks to "push", treat that as permission to commit and push all current workspace changes, not a hand-picked subset, unless they scope the push.
+
+## Verification gates
+
+Gates are defined once in `package.json` scripts; workflows and leaves invoke the scripts, never re-implement them. Rust and SDK gates are the named commands, and CI runs exactly these. Definition of done: `pnpm check:ci` green plus the tests below for touched surfaces.
+
+- Gate: `pnpm check:ci` = `pnpm typecheck` + `pnpm check:docs`; CI runs this.
+- Gate: `pnpm typecheck` - TypeScript across all workspaces.
+- Gate: `pnpm check:docs` - docs law via Deno (`scripts/check-docs.ts`).
+- Rust gates: `cargo test -p sandbox-agent-agent-management`, `cargo test -p sandbox-agent --test v1_api`, `--test v1_agent_process_matrix`, `--lib`.
+- SDK gate: `pnpm --dir sdks/typescript test`.
+- Merge, deploy, release, force-push, and credentials are human-approved; ask first.
+
+## Lint ratchet (end state, not yet wired)
+
+- End state: every package lints under oxlint with a per-package `oxlint.config.ts` extending `@systemfsoftware/all`; `pnpm lint` joins `check:ci`.
+- Today: lint is not wired (deps not installed; ~6,700 findings measured 2026-08-29 with oxlint 1.80.0 + `@systemfsoftware/all` 1.0.1 against the unliterated tree). Adoption is per package: add its `oxlint.config.ts`, fix its findings, then add `lint` to `check:ci` in the same commit.
+
+## Effect-first TypeScript
+
+- All TS surfaces adopt Effect-TS v4. Versions pin via the `catalogs.effect` block in `pnpm-workspace.yaml` when the first package adopts; the reference monorepo pins ^4.0.0-rc.112.
+- Idioms (reference: `github.com/systemfsoftware/systemfsoftware`, e.g. `packages/core/effect/daemon-spec/src/`): `Effect.gen`/`yield*`, `Context.Service` class services, `Layer.succeed`/`Layer.effect`, Schema declarations in `*.schema.ts` (`Schema.TaggedError`, `decodeUnknownExit`), property tests via `@effect/vitest it.prop`.
+- Foundry's actor runtime migrates from RivetKit to Effect's actor model (see `STRATEGY.md` Tracks). Until a module migrates, the law in `foundry/AGENTS.md` and `foundry/packages/backend/AGENTS.md` still binds; delete each rule as its module migrates.
+- Gate: the oxlint effect plugins shipped in `@systemfsoftware/all` (activated per package at adoption), plus `pnpm typecheck`.
+
+## Docs law
+
+- HTTP truth: `server/packages/sandbox-agent/src/router.rs`. CLI truth: `server/packages/sandbox-agent/src/cli.rs`. Document implemented surface only.
+- Never mention "ACP" in `docs/**/*.mdx` except pages that are about ACP; never expose protocol method names in non-ACP docs; document the SDK surface, not the protocol implementation; no em dashes in docs.
+  Gate: `pnpm check:docs` (`scripts/check-docs.ts`).
+- Docs styling is owned by the `@rivet-dev/docs-theme` repo consumed by `frontend/packages/website`; never restyle docs here. This site owns only content and `frontend/packages/website/docs.config.mjs`.
+- Keep `docs/cli.mdx` aligned with CLI behavior. Regenerate `docs/openapi.json` after HTTP contract changes. Gate: `pnpm generate`.
+- `docs/agent-capabilities.mdx`: when its "Last updated" is >2 weeks old or `fallback_config_options` changes, re-run `cd scripts/agent-configs && npx tsx dump.ts` and update it. Static docs list all known models regardless of subscription gating.
+
+## Sync obligations
+
+- CLI subcommands and HTTP endpoints stay in sync with each other.
+- Common-software trio stays in sync: `docs/common-software.mdx`, `docker/test-common-software/Dockerfile`, `server/packages/sandbox-agent/tests/common_software.rs`. Gate: `cargo test -p sandbox-agent --test common_software`.
+- Install-version channel policy: `sandbox-agent` installs use pinned minor `0.N.x` (curl URLs, `sandbox-agent` / `@sandbox-agent/cli`); gigacode installs use `latest` (`@sandbox-agent/gigacode`, `gigacode-install.*` promotion); a `latest` release updates `latest` and promotes sandbox-agent to the matching `0.N.x`. Affected files: `README.md`, `docs/acp-http-client.mdx`, `docs/cli.mdx`, `docs/quickstart.mdx`, `docs/sdk-overview.mdx`, `docs/react-components.mdx`, `docs/session-persistence.mdx`, `docs/deploy/*.mdx`, `frontend/packages/website/src/components/GetStarted.tsx`, `.claude/commands/post-release-testing.md`, `examples/cloudflare/Dockerfile`, `examples/daytona/src/index.ts`, `examples/shared/src/docker.ts`, `examples/{docker,e2b,vercel}/src/index.ts`, `scripts/release/{main,promote-artifacts,sdk}.ts`. (Gate earned after the rename lands: a `git grep` count over this list.)
+
+## Docker test images
+
+- Docker-backed tests build `docker/test-agent/Dockerfile` in-process and cache the tag in memory only (OnceLock / module-level variable); no cross-process image-build scripts.
+
+## Shared component rule
+
+- React UI shared between Inspector and Foundry is governed by `sdks/AGENTS.md`: change it in `sdks/react`, never fork it.

CLAUDE.md

@@ -1,84 +1 @@
-# Instructions
-
-## Naming and Ownership
-
-- This repository/product is **Sandbox Agent**.
-- **Gigacode** is a separate user-facing UI/client, not the server product name.
-- Gigacode integrates with Sandbox Agent via the OpenCode-compatible surface (`/opencode/*`) when that compatibility layer is enabled.
-- Canonical extension namespace/domain string is `sandboxagent.dev` (no hyphen).
-- Canonical custom ACP extension method prefix is `_sandboxagent/...` (no hyphen).
-
-## Docs Terminology
-
-- Never mention "ACP" in user-facing docs (`docs/**/*.mdx`) except in docs that are specifically about ACP itself (e.g. `docs/acp-http-client.mdx`).
-- Never expose underlying protocol method names (e.g. `session/request_permission`, `session/create`, `_sandboxagent/session/detach`) in non-ACP docs. Describe the behavior in user-facing terms instead.
-- Do not describe the underlying protocol implementation in docs. Only document the SDK surface (methods, types, options). ACP protocol details belong exclusively in ACP-specific pages.
-- Do not use em dashes (`—`) in docs. Use commas, periods, or parentheses instead.
-
-### Docs Source Of Truth (HTTP/CLI)
-
-- For HTTP/CLI docs/examples, source of truth is:
-  - `server/packages/sandbox-agent/src/router.rs`
-  - `server/packages/sandbox-agent/src/cli.rs`
-- Keep docs aligned to implemented endpoints/commands only (for example ACP under `/v1/acp`, not legacy session REST APIs).
-
-## Docs Styling
-
-- Docs styling is owned by the shared **`@rivet-dev/docs-theme`** repo (`github.com/rivet-dev/docs-theme`), consumed via `github:rivet-dev/docs-theme#<tag>` in `frontend/packages/website`. To change any docs styling (palette, header, sidebar, code blocks, fonts), edit that repo and follow its CLAUDE.md release workflow — never restyle docs here. This site owns only docs content + `frontend/packages/website/docs.config.mjs` (sidebar icons via each item's `attrs['data-icon']`).
-
-## Change Tracking
-
-- If the user asks to "push" changes, treat that as permission to commit and push all current workspace changes, not a hand-picked subset, unless the user explicitly scopes the push.
-- Keep CLI subcommands and HTTP endpoints in sync.
-- Update `docs/cli.mdx` when CLI behavior changes.
-- Regenerate `docs/openapi.json` when HTTP contracts change.
-- Keep `docs/inspector.mdx` and `docs/sdks/typescript.mdx` aligned with implementation.
-- Append blockers/decisions to `research/acp/friction.md` during ACP work.
-- `docs/agent-capabilities.mdx` lists models/modes/thought levels per agent. Update it when adding a new agent or changing `fallback_config_options`. If its "Last updated" date is >2 weeks old, re-run `cd scripts/agent-configs && npx tsx dump.ts` and update the doc to match. Source data: `scripts/agent-configs/resources/*.json` and hardcoded entries in `server/packages/sandbox-agent/src/router/support.rs` (`fallback_config_options`).
-- Some agent models are gated by subscription (e.g. Claude `opus`). The live report only shows models available to the current credentials. The static doc and JSON resource files should list all known models regardless of subscription tier.
-
-## Docker Test Image
-
-- Docker-backed Rust and TypeScript tests build `docker/test-agent/Dockerfile` directly in-process and cache the image tag only in memory (`OnceLock` in Rust, module-level variable in TypeScript).
-- Do not add cross-process image-build scripts unless there is a concrete need for them.
-
-## Common Software Sync
-
-- These three files must stay in sync:
-  - `docs/common-software.mdx` (user-facing documentation)
-  - `docker/test-common-software/Dockerfile` (packages installed in the test image)
-  - `server/packages/sandbox-agent/tests/common_software.rs` (test assertions)
-- When adding or removing software from `docs/common-software.mdx`, also add/remove the corresponding `apt-get install` line in the Dockerfile and add/remove the test in `common_software.rs`.
-- Run `cargo test -p sandbox-agent --test common_software` to verify.
-
-## Install Version References
-
-- Channel policy:
-  - Sandbox Agent install/version references use a pinned minor channel `0.N.x` (for curl URLs and `sandbox-agent` / `@sandbox-agent/cli` npm/bun installs).
-  - Gigacode install/version references use `latest` (for `@sandbox-agent/gigacode` install/run commands and `gigacode-install.*` release promotion).
-  - Release promotion policy: `latest` releases must still update `latest`; when a release is `latest`, Sandbox Agent must also be promoted to the matching minor channel `0.N.x`.
-- Keep every install-version reference below in sync whenever versions/channels change:
-  - `README.md`
-  - `docs/acp-http-client.mdx`
-  - `docs/cli.mdx`
-  - `docs/quickstart.mdx`
-  - `docs/sdk-overview.mdx`
-  - `docs/react-components.mdx`
-  - `docs/session-persistence.mdx`
-  - `docs/deploy/local.mdx`
-  - `docs/deploy/cloudflare.mdx`
-  - `docs/deploy/vercel.mdx`
-  - `docs/deploy/daytona.mdx`
-  - `docs/deploy/e2b.mdx`
-  - `docs/deploy/docker.mdx`
-  - `frontend/packages/website/src/components/GetStarted.tsx`
-  - `.claude/commands/post-release-testing.md`
-  - `examples/cloudflare/Dockerfile`
-  - `examples/daytona/src/index.ts`
-  - `examples/shared/src/docker.ts`
-  - `examples/docker/src/index.ts`
-  - `examples/e2b/src/index.ts`
-  - `examples/vercel/src/index.ts`
-  - `scripts/release/main.ts`
-  - `scripts/release/promote-artifacts.ts`
-  - `scripts/release/sdk.ts`
+@AGENTS.md

STRATEGY.md

@@ -0,0 +1,63 @@
+---
+name: Systemfsoftware
+last_updated: 2026-08-29
+---
+
+# Systemfsoftware Strategy
+
+## Purpose
+
+Developers embedding coding agents (Claude Code, Codex, OpenCode, Cursor, Amp, Pi) into products hit the same wall: every agent speaks a different protocol, sessions die with the sandbox, and remote control over HTTP has to be rebuilt per agent. Systemfsoftware exists to remove that wall: one control plane that runs in the sandbox and speaks to every agent.
+
+## Positioning
+
+L'État, c'est moi. Systemfsoftware is not a competitor in the agent-tooling market; it is the lawgiver of it: the Effect-TS idiom set, the oxlint rulebook, and the sandbox control plane are the standard other products conform to. A neighboring product can integrate with Systemfsoftware; it cannot truthfully claim to define the standard.
+
+## Users
+
+**Primary:** Platform engineer embedding agent control. They're hiring Systemfsoftware to run any coding agent inside a sandbox and control it over HTTP without per-agent rewrites.
+
+**Secondary:** Foundry operator. They're hiring the Foundry tree to run multi-repo agent tasks with GitHub-backed state and realtime UI.
+
+## Boundaries
+
+- No session storage on disk; consumers stream events to their own storage.
+- No direct LLM wrappers; the Vercel AI SDK stays complementary.
+- No sandbox-provider API layer; providers get guides, not abstractions.
+- No polling, retry loops, or manual-refresh flows in Foundry; push-based progression only.
+
+_Resist a change when:_ a provider asks for a custom API surface; guides and the existing HTTP contracts come first.
+
+## Key metrics
+
+- **Green CI with lint gates** - `ci.yaml` passes with oxlint (`@systemfsoftware/all`) in the chain; measured on GitHub Actions.
+- **Rename completeness** - zero new occurrences of `rivet-dev` org refs, `@sandbox-agent` scope, or `sandboxagent.dev` outside migration notes; checked by `git grep` count.
+- **Effect coverage of TS surfaces** - sdks, frontend, and foundry-backend packages compile under Effect v4 with per-package `oxlint.config.ts`; checked by `pnpm typecheck` and `pnpm lint`.
+
+Flip to product metrics (installs, session success rate) after the refactor ships.
+
+## Tracks
+
+### Banner migration
+
+Repo, org, npm scopes, crates, domain, and product display name become systemfsoftware / Systemfsoftware.
+
+_Why it serves the approach:_ one name that is the standard is the precondition for the positioning.
+
+### Effect v4 adoption
+
+All TS surfaces move to Effect v4 via pnpm catalogs; Foundry's RivetKit actor runtime is replaced by Effect's actor model.
+
+_Why it serves the approach:_ the platform's law is Effect; running products on a different runtime contradicts it.
+
+### Lint sovereignty
+
+Every package lints under `@systemfsoftware/all` through per-package `oxlint.config.ts`, with gates defined once in the check chain.
+
+_Why it serves the approach:_ law without deterministic enforcement is prose.
+
+## Brand
+
+**One-liner:** Systemfsoftware is the state of coding-agent infrastructure: one control plane, one type system, one rulebook.
+
+**Key message:** Other tools ask which agent framework you picked. Systemfsoftware is the framework the agents answer to.

docs/deploy/boxlite.mdx

@@ -3,7 +3,7 @@ title: "BoxLite"
 description: "Run Sandbox Agent inside a BoxLite micro-VM."
 ---
 
-BoxLite is a local-first micro-VM sandbox — no cloud account needed.
+BoxLite is a local-first micro-VM sandbox, no cloud account needed.
 See [BoxLite docs](https://docs.boxlite.ai) for platform requirements (KVM on Linux, Apple Silicon on macOS).
 
 ## Prerequisites

docs/processes.mdx

@@ -7,11 +7,11 @@ icon: "terminal"
 
 The process API supports:
 
-- **One-shot execution** — run a command to completion and capture stdout, stderr, and exit code
-- **Managed processes** — spawn, list, stop, kill, and delete long-lived processes
-- **Log streaming** — fetch buffered logs or follow live output
-- **Terminals** — full PTY support with bidirectional WebSocket I/O
-- **Configurable limits** — control concurrency, timeouts, and buffer sizes per runtime
+- **One-shot execution**: run a command to completion and capture stdout, stderr, and exit code
+- **Managed processes**: spawn, list, stop, kill, and delete long-lived processes
+- **Log streaming**: fetch buffered logs or follow live output
+- **Terminals**: full PTY support with bidirectional WebSocket I/O
+- **Configurable limits**: control concurrency, timeouts, and buffer sizes per runtime
 
 ## Run a command
 

docs/sdk-overview.mdx

@@ -85,7 +85,7 @@ const sdk = await SandboxAgent.start({
   sandbox: local(),
 });
 
-// sdk.sandboxId — prefixed provider ID (e.g. "local/127.0.0.1:2468")
+// sdk.sandboxId: prefixed provider ID (e.g. "local/127.0.0.1:2468")
 
 await sdk.destroySandbox(); // provider-defined cleanup + disposes client
 ```

examples/AGENTS.md

@@ -0,0 +1,12 @@
+# Examples Instructions
+
+## Docker isolation
+
+- Docker examples behave as standalone sandboxes: no host bind mounts of files or directories.
+- Needed tools, skills, or MCP servers are installed inside the container during setup.
+
+## Validation
+
+- Validate examples against the implemented server surface (`server/packages/sandbox-agent/src/router.rs`), not against narrated flows in docs.
+- Bleeding-edge local testing: `SANDBOX_AGENT_DEV=1 pnpm start` builds `docker/runtime/Dockerfile.full` from local source.
+- Drive the ACP surface with the `mock` agent (initialize, then session/new, session/prompt; SSE for events) exactly as the SDK does; keep any example README instructions aligned with `server/ARCHITECTURE.md`.

examples/CLAUDE.md

@@ -1,22 +1 @@
-# Examples Instructions
-
-## Docker Isolation
-
-- Docker examples must behave like standalone sandboxes.
-- Do not bind mount host files or host directories into Docker example containers.
-- If an example needs tools, skills, or MCP servers, install them inside the container during setup.
-
-## Testing Examples (ACP v2)
-
-Examples should be validated against v2 endpoints:
-
-1. Start the example: `SANDBOX_AGENT_DEV=1 pnpm start`
-2. Create an ACP client by POSTing `initialize` to `/v2/rpc` with `x-acp-agent: mock` (or another installed agent).
-3. Capture `x-acp-connection-id` from the response headers.
-4. Open SSE stream: `GET /v2/rpc` with `x-acp-connection-id`.
-5. Send `session/new` then `session/prompt` via `POST /v2/rpc` with the same connection id.
-6. Close connection via `DELETE /v2/rpc` with `x-acp-connection-id`.
-
-v1 reminder:
-
-- `/v1/*` is removed and returns `410 Gone`.
+@AGENTS.md