> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase06-session05-isolation-boundary-and-sandbox-diagnostics/spec.md).

# Session Specification

**Session ID**: `phase06-session05-isolation-boundary-and-sandbox-diagnostics` **Phase**: 06 - Collaboration, Isolation, and Mobile **Status**: Not Started **Created**: 2026-05-30 **Package**: cross-cutting (`packages/protocol`, `apps/server`, `apps/cli`, `apps/hooks`) **Package Stack**: TypeScript and JavaScript

***

## 1. Session Overview

This session defines and exposes the local isolation boundary for FactionOS without adding real file, git, terminal, Docker, remote, or hosted executors. It turns the Phase 06 baseline into shared protocol vocabulary, compact server diagnostics, deterministic unsupported-route behavior, and CLI or hook-facing posture summaries.

The work matters because guarded actions and historical route families already look close to execution surfaces. Users and maintainers need explicit evidence that approval records intent only, current execution remains unavailable, and diagnostics reveal posture without exposing prompts, command bodies, terminal output, file contents, tokens, broad paths, raw spool data, logs, backups, or state files.

The session follows the Phase 06 routing matrix after collaboration contracts and cockpit UX work. It prepares Session 07 closeout evidence by making isolation posture testable in protocol, server, CLI, hook, and docs surfaces before mobile/accessibility hardening and final validation proceed.

***

## 2. Objectives

1. Define a source-backed isolation threat model for current unavailable execution and future executor families.
2. Add protocol-owned sandbox posture and diagnostic contracts before server and CLI consumers use them.
3. Expose compact local isolation diagnostics in server and CLI surfaces with no mutation, no raw payloads, and deterministic failure labels.
4. Prove unsupported execution and diagnostics remain deterministic, redacted, and non-executing through focused tests and docs.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase06-session01-collaboration-requirements-and-safety-baseline` - Defines the isolation, sandbox, redaction, mobile, and deferral baseline.
* [x] `phase06-session02-room-authority-and-participant-identity-contracts` - Keeps collaboration authority separate from local execution claims.
* [x] `phase06-session03-shared-collaboration-event-contracts` - Establishes blocked payload categories that diagnostics must not transfer.
* [x] `phase06-session04-collaborative-cockpit-ux-and-remote-context` - Keeps remote context separate from local guarded-action source-of-truth state.
* [x] `phase03-session04-guarded-local-action-runtime` - Provides current guarded-action proposal, decision, and unavailable result behavior.
* [x] `phase03-session06-cli-diagnostics-and-recovery-controls` - Provides current compact CLI diagnostics and narrow recovery posture.

### Required Tools/Knowledge

* npm workspaces, Node 20+, TypeScript, Vitest, and Biome.
* Existing protocol ownership pattern in `packages/protocol/src/index.ts`.
* Existing local diagnostics and redaction boundaries in server, CLI, and hook README files.

### Environment Requirements

* Local dependencies installed with `npm install`.
* Tests runnable from the repo root with focused Vitest commands.
* No Cloudflare Worker URL, Docker daemon, hosted account, analytics key, or remote runner is required.

***

## 4. Scope

### In Scope (MVP)

* A maintainer can inspect the current isolation threat model - add source-backed future executor requirements for file, git, terminal, Docker/container, remote, and hosted execution.
* A runtime consumer can import shared isolation vocabulary - add protocol contracts for sandbox posture, unavailable execution reasons, diagnostic summaries, consent, audit, rollback, and redaction categories.
* A local client can request isolation posture - expose compact server diagnostics with availability, configuration, counts, and labels only.
* A CLI user can see isolation posture - surface status and doctor summaries without raw prompts, command bodies, paths, tokens, spool payloads, logs, backups, or state files.
* A hook maintainer can see the executor boundary - update hook guidance so handlers remain silent, timeout-safe, sanitized, and non-executing.
* A tester can verify unsupported execution - add focused tests for diagnostics, unsupported routes, guarded-action unavailability, redaction, and no-mutation behavior.

### Out of Scope (Deferred)

* Running file, git, terminal, Docker, remote, or hosted commands - *Reason: requires a later approved executor threat model and implementation session.*
* Adding a container runtime, remote runner, cloud VM, hosted queue worker, or inbound command bridge - *Reason: Phase 06 owns posture and diagnostics only.*
* Trusted unified erasure for Worker state, browser hints, archives, exports, replay buffers, diagnostics, logs, backups, valid spool state, or future hosted data - *Reason: Phase 08 owns release-grade erasure.*
* Hosted identity, hosted storage, analytics, public replay hosting, production-hosted validation, or mobile certification - *Reason: later phases own hosted services and release validation.*

***

## 5. Technical Approach

### Architecture

Start with `packages/protocol` so isolation vocabulary and diagnostic shapes are shared rather than duplicated. The protocol contract should describe executor families, capability posture, unavailable execution reasons, redaction categories, consent and audit requirements, and compact diagnostic sections.

Server code should build isolation diagnostics from existing in-memory managers and static runtime capabilities. The diagnostics route must inherit the same local auth, CORS, rate-limit, and body-size middleware as the current diagnostics route. It should return bounded labels and counts only. It must not inspect or mutate local files, valid spool state, archives, browser state, Worker state, backups, or workspace files.

CLI code should consume the compact diagnostics with loopback-only requests, timeouts, sanitized failure labels, and offline fallback. Hook work remains guidance and test reinforcement: hooks keep sending observability events and diagnostic metadata only, not execution instructions.

### Design Patterns

* Protocol-first contracts: shared vocabulary lands in `packages/protocol` before server or CLI consumers depend on it.
* Boundary-specific redaction: diagnostics, unsupported routes, guarded actions, hooks, CLI, exports, replay, Worker frames, and logs do not share a blanket "safe" assumption.
* Explicit unavailable states: approved guarded actions return unavailable or not-executed results until an executor is deliberately added.
* Compact diagnostics: output counts, status labels, family labels, posture, timestamps, and docs paths, never raw local payloads.

### Technology Stack

* TypeScript in `packages/protocol` and `apps/server`.
* JavaScript in `apps/cli` and `apps/hooks`.
* Vitest for focused protocol, server, CLI, and hook tests.
* Biome for formatting and linting.

***

## 6. Deliverables

### Files to Create

| File                                             | Purpose                                                                  | Est. Lines |
| ------------------------------------------------ | ------------------------------------------------------------------------ | ---------- |
| `docs/isolation-and-sandbox.md`                  | Source-backed threat model and future executor requirements.             | \~160      |
| `packages/protocol/src/isolation.ts`             | Shared isolation posture, executor, diagnostic, and redaction contracts. | \~180      |
| `packages/protocol/tests/isolation.test.ts`      | Protocol vocabulary and diagnostic shape tests.                          | \~120      |
| `apps/server/src/lib/isolationDiagnostics.ts`    | Compact server-side isolation diagnostic builder.                        | \~180      |
| `apps/server/tests/isolationDiagnostics.test.ts` | Server diagnostics, redaction, auth, and no-mutation tests.              | \~160      |

### Files to Modify

| File                                                | Changes                                                                                    | Est. Lines |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------ | ---------- |
| `packages/protocol/src/index.ts`                    | Export isolation contracts.                                                                | \~2        |
| `packages/protocol/src/rest.ts`                     | Refine route family vocabulary for container and hosted executor envelopes.                | \~20       |
| `packages/protocol/tests/rest.test.ts`              | Cover route family vocabulary and compact unsupported envelopes.                           | \~30       |
| `packages/protocol/README_protocol.md`              | Document protocol ownership for isolation contracts.                                       | \~25       |
| `apps/server/src/routes/diagnostics.ts`             | Add isolation diagnostics route or route wiring.                                           | \~30       |
| `apps/server/src/lib/orchestrationDiagnostics.ts`   | Include an isolation summary in orchestration diagnostics if needed for CLI compatibility. | \~40       |
| `apps/server/src/lib/unsupportedRoutes.ts`          | Preserve deterministic unsupported-route classification by executor family.                | \~60       |
| `apps/server/src/managers/guardedActions.ts`        | Keep approved actions unavailable with family-specific reasons.                            | \~35       |
| `apps/server/tests/unsupportedRoutes.test.ts`       | Assert redacted deterministic 501 envelopes for isolation-owned families.                  | \~60       |
| `apps/server/tests/guardedActions.test.ts`          | Assert approvals do not execute or mutate local state.                                     | \~60       |
| `apps/server/README_server.md`                      | Document isolation diagnostics and no-execution boundary.                                  | \~30       |
| `apps/cli/src/lib/orchestrationDiagnostics.js`      | Compact isolation diagnostics and sanitize failures.                                       | \~80       |
| `apps/cli/src/commands/status.js`                   | Print isolation posture in status output.                                                  | \~20       |
| `apps/cli/src/commands/doctor.js`                   | Print and check isolation posture in doctor output.                                        | \~25       |
| `apps/cli/tests/orchestrationDiagnostics.test.js`   | Cover compact isolation diagnostics and redaction.                                         | \~80       |
| `apps/cli/tests/cliRuntime.test.js`                 | Cover status and doctor isolation output.                                                  | \~40       |
| `apps/cli/README_cli.md`                            | Document CLI isolation posture and recovery boundary.                                      | \~30       |
| `apps/hooks/README_hooks.md`                        | Document hook executor boundary and diagnostic limits.                                     | \~25       |
| `apps/hooks/tests/orchestrationDiagnostics.test.js` | Reinforce hook diagnostics as silent, sanitized, and non-executing.                        | \~40       |
| `docs/api/event-api-hook-contracts.md`              | Add isolation diagnostics contract and executor deferral language.                         | \~70       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Isolation posture is explicit through docs, protocol contracts, server diagnostics, and CLI output.
* [ ] Current guarded-action approval remains non-executing and returns explicit unavailable or not-executed results.
* [ ] Unsupported file, git, terminal, container, remote, hosted, Worker, collaboration, channel, push, webhook, and settings routes return deterministic compact envelopes.
* [ ] Hook guidance keeps future executor signals bounded, timeout-safe, sanitized, silent during normal operation, and non-executing.

### Testing Requirements

* [ ] Protocol tests cover isolation vocabulary, diagnostic shapes, redaction categories, and exhaustive enum handling.
* [ ] Server tests cover diagnostics, unsupported route envelopes, guarded-action unavailability, auth inheritance, redaction, and no local mutation.
* [ ] CLI tests cover compact status/doctor output, loopback-only diagnostics, timeouts, sanitized errors, and recovery boundaries.
* [ ] Hook tests or docs-backed checks reinforce no stdout/stderr raw payloads and no inbound execution.

### Non-Functional Requirements

* [ ] Diagnostics expose compact status only and avoid raw local payloads, paths, commands, logs, backups, state files, and raw spool entries.
* [ ] Runtime remains local-first with no dependency on Docker, Cloudflare, hosted services, analytics, public replay hosting, media providers, remote runners, or provider credentials.
* [ ] The implementation does not mutate workspace files, valid local state, browser state, Worker state, logs, backups, archives, or valid spool entries while collecting diagnostics.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Focused Vitest suites pass.
* [ ] `npm run format:check` or focused Biome checks pass for changed files.

***

## 8. Implementation Notes

### Key Considerations

* Protocol contracts should not imply that real executors exist.
* Server diagnostics should be generated from known capabilities and bounded counts, not from raw queue entries, proposal rationale, local files, logs, or backups.
* CLI output should describe recovery as narrow diagnostics cleanup only, not trusted erasure.
* Hook docs should preserve the current silent, timeout-safe handler model.

### Potential Challenges

* Route family vocabulary drift: Keep `packages/protocol/src/rest.ts`, `apps/server/src/lib/unsupportedRoutes.ts`, tests, and API docs aligned.
* Overstating safety: Use "unavailable", "not executed", "planned", and "deferred" wording instead of implying sandboxed execution exists.
* Diagnostics leakage: Tests should assert blocked strings do not appear in JSON, CLI output, or unsupported-route envelopes.
* Scope creep into executors: Guarded-action work must stop at unavailable result mapping and diagnostics.

### Relevant Considerations

* \[P03] **Real executors remain unimplemented by design**: This session keeps guarded actions as proposals and decisions only while documenting the future threat model.
* \[P05] **Redaction is boundary-specific**: Isolation diagnostics get explicit blocked categories instead of inheriting Worker or export safety assumptions.
* \[P03-apps/server+packages/protocol] **Unsupported historical routes are explicit 501s**: Route envelopes stay deterministic rather than becoming accidental 404s or half-wired parity.
* \[P03-apps/cli+apps/hooks] **Lifecycle state is local and file-based**: CLI and hook diagnostics must not mutate valid local state or print broad paths.
* \[P05] **Unified erasure still missing**: Recovery and cleanup wording must not claim trusted deletion.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Diagnostics accidentally expose sensitive prompts, commands, paths, logs, backups, state files, or raw spool data.
* Guarded-action approval copy or result mapping implies execution happened.
* Unsupported historical routes drift into accidental route parity or unsafe request echoing.
* CLI recovery wording implies trusted erasure rather than narrow diagnostic cleanup.

***

## 9. Testing Strategy

### Unit Tests

* Protocol tests for isolation enum values, contract shapes, redaction categories, unavailable reasons, and exhaustive family coverage.
* Server tests for isolation diagnostic builder output and guarded-action unavailable mapping.
* CLI tests for compact diagnostics parsing, sanitized error handling, and status/doctor output.

### Integration Tests

* Server route tests for `GET /diagnostics/isolation`, auth inheritance, and deterministic unsupported-route envelopes.
* Existing guarded-action route tests extended to prove approved actions do not execute and return unavailable results.

### Manual Testing

* Run `factionos status` and `factionos doctor` against online and offline local server states to verify readable isolation posture and no raw local payloads.
* Review generated docs and README updates for explicit deferred executor, erasure, hosted-service, and production-validation boundaries.

### Edge Cases

* Missing diagnostics route, unauthorized route, invalid JSON response, server timeout, and non-loopback server URL.
* Unsupported routes with query strings, body payloads, token-like values, command previews, and private paths.
* Guarded actions for file, git, terminal, remote access, and container families after approval.
* Malformed hook log lines, stale listener PIDs, malformed spool entries, and valid spool entries that must not be removed unless explicitly malformed.

***

## 10. Dependencies

### External Libraries

* No new external runtime libraries planned.
* Existing `@factionos/protocol`, Express, Vitest, and Node standard library utilities are sufficient.

### Other Sessions

* **Depends on**: `phase06-session01-collaboration-requirements-and-safety-baseline`, `phase03-session04-guarded-local-action-runtime`, `phase03-session06-cli-diagnostics-and-recovery-controls`.
* **Depended by**: `phase06-session07-collaboration-isolation-and-mobile-validation-closeout`.

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase06-session05-isolation-boundary-and-sandbox-diagnostics/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.