> 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/implementation-notes.md). # Implementation Notes **Session ID**: `phase06-session05-isolation-boundary-and-sandbox-diagnostics` **Package**: cross-cutting (`packages/protocol`, `apps/server`, `apps/cli`, `apps/hooks`) **Started**: 2026-05-30 06:02 **Last Updated**: 2026-05-30 06:18 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 22 / 22 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### 2026-05-30 - Session Start **Environment verified**: * [x] Apex spec analysis run with bundled fallback script * [x] Prerequisites confirmed * [x] Tools available: Node v24.14.0, npm 10.5.1, Vitest 4.1.7, Biome 2.4.16 * [x] Directory structure ready * [x] Database not configured for this project *** ### Task T001 - Verify Phase 06 isolation prerequisites and routing evidence **Started**: 2026-05-30 06:00 **Completed**: 2026-05-30 06:02 **Duration**: 2 minutes **Notes**: * Confirmed the active session is `phase06-session05-isolation-boundary-and-sandbox-diagnostics`. * Verified Session 05 routes P06-R003 and P06-R019 through P06-R023 from the Phase 06 requirement matrix. * Confirmed the Phase 06 baseline keeps guarded actions non-executing and file, git, terminal, Docker, remote, and hosted executors unavailable. * Confirmed ADR 0001 keeps the local-first npm workspace as the runtime baseline. **Files Changed**: * `.spec_system/specs/phase06-session05-isolation-boundary-and-sandbox-diagnostics/implementation-notes.md` - recorded environment and routing evidence. *** ### Task T002 - Inventory current guarded-action, unsupported-route, CLI, and hook diagnostic anchors **Started**: 2026-05-30 06:02 **Completed**: 2026-05-30 06:03 **Duration**: 1 minute **Notes**: * Guarded actions are owned by `packages/protocol/src/guardedActions.ts` and `apps/server/src/managers/guardedActions.ts`; approvals currently become `unavailable`. * Unsupported route envelopes are owned by `packages/protocol/src/rest.ts` and `apps/server/src/lib/unsupportedRoutes.ts`, then served from the `app.all("*")` catch-all in `apps/server/src/server.ts`. * Server orchestration diagnostics are built in `apps/server/src/lib/orchestrationDiagnostics.ts` and mounted by `apps/server/src/routes/diagnostics.ts`. * CLI diagnostics are fetched and compacted in `apps/cli/src/lib/orchestrationDiagnostics.js`, then printed by `apps/cli/src/commands/status.js` and `apps/cli/src/commands/doctor.js`. * Hook diagnostics are summarized in `apps/hooks/src/_lib.js` and `apps/hooks/src/ws-listener.js`; hook docs already require silence, bounded POSTs, sanitized logs, and no inbound execution. **Files Changed**: * `.spec_system/specs/phase06-session05-isolation-boundary-and-sandbox-diagnostics/implementation-notes.md` - recorded source anchors for implementation. *** ### Task T003 - Create the isolation threat model scaffold for future executor families **Started**: 2026-05-30 06:03 **Completed**: 2026-05-30 06:04 **Duration**: 1 minute **Notes**: * Added the source-backed isolation document with current runtime boundaries, future executor families, compact diagnostic constraints, and recovery limits. * Kept all file, git, terminal, Docker, remote, Worker, hosted, and browser-to-terminal executor families explicitly unavailable. **Files Changed**: * `docs/isolation-and-sandbox.md` - added the initial isolation and sandbox threat-model scaffold. *** ### Task T004 - Create protocol isolation posture and diagnostic contracts **Started**: 2026-05-30 06:04 **Completed**: 2026-05-30 06:06 **Duration**: 2 minutes **Notes**: * Added protocol-owned executor family, route family, posture, unavailable reason, requirement, and redaction vocabularies. * Added compact isolation diagnostic summary shapes for executor posture, guarded actions, unsupported routes, redaction, and narrow recovery. * Added helper guards and exhaustive switch handling for executor unavailable reasons. **Files Changed**: * `packages/protocol/src/isolation.ts` - new shared isolation contracts and helpers. **BQC Fixes**: * Contract alignment: protocol constants and records use typed exhaustive mappings for executor families. *** ### Task T005 - Export protocol isolation contracts from the package barrel **Started**: 2026-05-30 06:06 **Completed**: 2026-05-30 06:07 **Duration**: 1 minute **Notes**: * Exported `src/isolation.ts` from the package root barrel. **Files Changed**: * `packages/protocol/src/index.ts` - added isolation contract export. *** ### Task T006 - Refine REST route family vocabulary for executor envelopes **Started**: 2026-05-30 06:07 **Completed**: 2026-05-30 06:08 **Duration**: 1 minute **Notes**: * Added `container-operations`, `hosted-services`, `worker-execution`, and `channels` as explicit REST route families. * Added compact unsupported status mapping for execution and collaboration-style route families. **Files Changed**: * `packages/protocol/src/rest.ts` - refined route family vocabulary and compact status helper. **BQC Fixes**: * Contract alignment: unsupported status defaults are protocol-owned and typed against `RestRouteFamily`. *** ### Task T007 - Document protocol ownership of isolation contracts **Started**: 2026-05-30 06:08 **Completed**: 2026-05-30 06:09 **Duration**: 1 minute **Notes**: * Documented `src/isolation.ts` as protocol-owned vocabulary for executor posture, unavailable reasons, controls, redaction, recovery, and compact diagnostics. * Reiterated that protocol isolation contracts do not imply shipped executors. **Files Changed**: * `packages/protocol/README_protocol.md` - added Session 05 isolation ownership notes. *** ### Task T008 - Update API contract for isolation diagnostics and unsupported families **Started**: 2026-05-30 06:09 **Completed**: 2026-05-30 06:10 **Duration**: 1 minute **Notes**: * Added `GET /diagnostics/isolation` to the shipped REST route table with read-only compact-output constraints. * Documented no raw request echo and no mutation side effects for isolation diagnostics. * Split container, hosted, and Worker execution route families into explicit historical classification rows. **Files Changed**: * `docs/api/event-api-hook-contracts.md` - documented isolation diagnostics and unsupported executor families. *** ### Task T009 - Create server isolation diagnostics builder **Started**: 2026-05-30 06:10 **Completed**: 2026-05-30 06:12 **Duration**: 2 minutes **Notes**: * Added a server diagnostic builder that returns protocol-shaped isolation posture, unavailable executor capabilities, guarded-action counts, deterministic unsupported-route families, redaction category counts, and narrow recovery limits. * Counts are bounded and ordered deterministically. The builder reads manager counts only and does not inspect raw proposals, queue entries, files, logs, archives, backups, or spool payloads. **Files Changed**: * `apps/server/src/lib/isolationDiagnostics.ts` - added compact isolation diagnostics snapshot builder. **BQC Fixes**: * Failure path completeness: diagnostics expose compact status labels without relying on raw manager payload reads. * Error information boundaries: blocked categories are labels only; no local payload content is included. *** ### Task T010 - Wire the isolation diagnostics route **Started**: 2026-05-30 06:12 **Completed**: 2026-05-30 06:13 **Duration**: 1 minute **Notes**: * Mounted `GET /diagnostics/isolation` in the existing diagnostics router. * Reused the app-level middleware path so CORS, local auth, rate limiting, and body-size behavior stay aligned with other server routes. * Added compact 503 error mapping for route builder failures. **Files Changed**: * `apps/server/src/routes/diagnostics.ts` - added isolation diagnostics route wiring. **BQC Fixes**: * Failure path completeness: route-level builder errors return a compact `diagnostics_unavailable` envelope. *** ### Task T011 - Extend orchestration diagnostics with isolation summary **Started**: 2026-05-30 06:13 **Completed**: 2026-05-30 06:14 **Duration**: 1 minute **Notes**: * Added a compact `isolation` section to orchestration diagnostics for CLI compatibility. * The summary exposes only non-executing posture, executor totals, guarded-action counts, and docs paths. **Files Changed**: * `apps/server/src/lib/orchestrationDiagnostics.ts` - added compact isolation summary. **BQC Fixes**: * Contract alignment: orchestration diagnostics and the dedicated isolation diagnostics route now share protocol-owned family counts and docs paths. *** ### Task T012 - Refine unsupported route classification for isolation-owned families **Started**: 2026-05-30 06:14 **Completed**: 2026-05-30 06:16 **Duration**: 2 minutes **Notes**: * Split container, remote, hosted, Worker execution, channel, collaboration, push, webhook, and settings families into deterministic route classifications. * Used protocol compact unsupported status mapping so route family status is shared. * Normalized unsupported response paths by stripping query/hash data, bounding path segments, and redacting secret-like segments without echoing request bodies. **Files Changed**: * `apps/server/src/lib/unsupportedRoutes.ts` - refined family classification and response path redaction. **BQC Fixes**: * Error information boundaries: unsupported envelopes never include request bodies and now further bound path detail. * Trust boundary enforcement: unsupported route families fail closed with deterministic 501 classification. *** ### Task T013 - Tighten guarded-action unavailable result mapping **Started**: 2026-05-30 06:16 **Completed**: 2026-05-30 06:18 **Duration**: 2 minutes **Notes**: * Added family-specific unavailable reasons and messages for file, git, terminal, subagent, mission, handoff, remote, and container guarded actions. * Approval remains a non-executing state transition to `unavailable`; no executor or workspace mutation was added. **Files Changed**: * `apps/server/src/managers/guardedActions.ts` - added exhaustive family-specific unavailable mapping. **BQC Fixes**: * Contract alignment: guarded-action family handling is exhaustive at compile time. * Error information boundaries: unavailable messages are stable posture labels and do not include proposal rationale or preview details. *** ### Task T014 - Update server, CLI, and hook README boundary notes **Started**: 2026-05-30 06:13 **Completed**: 2026-05-30 06:14 **Duration**: 1 minute **Notes**: * Documented `GET /diagnostics/isolation` in the server README and reiterated no raw local payloads or mutations. * Added CLI status/doctor isolation posture and narrow recovery boundaries. * Reinforced hook-side silence, sanitized diagnostics, and no inbound execution behavior. **Files Changed**: * `apps/server/README_server.md` - documented isolation diagnostics and non-executing guarded-action posture. * `apps/cli/README_cli.md` - documented compact isolation output and no trusted-erasure claims. * `apps/hooks/README_hooks.md` - documented hook executor boundary and diagnostic limits. *** ### Task T015 - Update CLI diagnostics parsing for isolation posture **Started**: 2026-05-30 06:14 **Completed**: 2026-05-30 06:15 **Duration**: 1 minute **Notes**: * Added `fetchIsolationDiagnostics()` with the same loopback-only URL enforcement, timeout handling, bearer auth support, and sanitized failure handling used by orchestration diagnostics. * Added compact isolation response parsing that preserves only posture labels, executor counts/families, guarded-action counts, unsupported-route family labels, redaction category count, and narrow recovery flags. * Added a compact embedded orchestration isolation parser for compatibility with `/diagnostics/orchestration`. **Files Changed**: * `apps/cli/src/lib/orchestrationDiagnostics.js` - added isolation diagnostics fetch, compacting, and description helpers. **BQC Fixes**: * External dependency resilience: isolation diagnostics use bounded local HTTP requests and explicit timeout failure labels. * Error information boundaries: CLI compaction drops raw diagnostic payload fields and sanitizes failure text. *** ### Task T016 - Add isolation posture to CLI status output **Started**: 2026-05-30 06:15 **Completed**: 2026-05-30 06:16 **Duration**: 1 minute **Notes**: * `factionos status` now fetches compact isolation diagnostics and prints non-executing posture, unavailable executor counts, guarded-action posture, and narrow recovery state. * Added fallback to the embedded orchestration isolation summary when the dedicated route is unavailable but the server provides the compact summary. * Added route-missing failure labels for isolation diagnostics. **Files Changed**: * `apps/cli/src/commands/status.js` - added isolation status output. **BQC Fixes**: * Failure path completeness: status output reports route missing, timeout, auth-required, offline, and malformed isolation diagnostics as visible labels. *** ### Task T017 - Add isolation posture checks to CLI doctor **Started**: 2026-05-30 06:16 **Completed**: 2026-05-30 06:17 **Duration**: 1 minute **Notes**: * `factionos doctor` now checks the isolation diagnostics route when the server is reachable. * Added explicit checks that executor posture remains non-executing/unavailable and recovery remains narrow without trusted erasure claims. **Files Changed**: * `apps/cli/src/commands/doctor.js` - added isolation diagnostics checks and compact posture output. **BQC Fixes**: * Failure path completeness: doctor reports a missing isolation route as a visible local diagnostic failure. * Error information boundaries: doctor prints compact labels and counts only. *** ### Task T018 - Complete the isolation threat model **Started**: 2026-05-30 06:17 **Completed**: 2026-05-30 06:18 **Duration**: 1 minute **Notes**: * Expanded the isolation document with concrete consent, authorization, audit, idempotency, rollback, redaction, and validation requirements for future executor sessions. * Kept current recovery wording narrow and avoided trusted-erasure or shipped-executor claims. **Files Changed**: * `docs/isolation-and-sandbox.md` - completed future executor threat-model requirements. *** ### Task T019 - Add protocol isolation and route family tests **Started**: 2026-05-30 06:18 **Completed**: 2026-05-30 06:18 **Duration**: <1 minute **Notes**: * Added isolation protocol tests for executor vocabulary, unavailable reasons, control requirements, redaction categories, diagnostic shape, and type alignment. * Extended REST tests for container, hosted, Worker execution, channel families, and compact unsupported status mapping. **Files Changed**: * `packages/protocol/tests/isolation.test.ts` - added isolation contract tests. * `packages/protocol/tests/rest.test.ts` - extended REST route vocabulary and status mapping tests. *** ### Task T020 - Add server isolation diagnostics and unavailable route tests **Started**: 2026-05-30 06:18 **Completed**: 2026-05-30 06:18 **Duration**: <1 minute **Notes**: * Added server route tests for compact isolation diagnostics, auth inheritance, redaction, and read-only guarded-action behavior. * Extended unsupported route tests for container, hosted, Worker execution, channel, and path-bounding behavior. * Extended guarded-action tests for remote and subagent family-specific unavailable reasons. **Files Changed**: * `apps/server/tests/isolationDiagnostics.test.ts` - added isolation diagnostics route and builder tests. * `apps/server/tests/unsupportedRoutes.test.ts` - added isolation-owned unsupported route family coverage. * `apps/server/tests/guardedActions.test.ts` - added family-specific unavailable result coverage. **BQC Fixes**: * Trust boundary enforcement: auth inheritance and unsupported-route fail-closed behavior are covered. * State freshness on re-entry: diagnostics builder test proves collection does not expire guarded actions. * Error information boundaries: tests assert raw guarded-action and route payload details are not echoed. *** ### Task T021 - Add CLI and hook isolation diagnostics tests **Started**: 2026-05-30 06:18 **Completed**: 2026-05-30 06:18 **Duration**: <1 minute **Notes**: * Added CLI diagnostics tests for compact isolation parsing, bearer auth, non-loopback rejection, sanitized payload dropping, and description output. * Extended CLI runtime tests so status and doctor print isolation posture and narrow recovery labels. * Added hook diagnostics coverage for inbound execution-shaped listener frames remaining summarized, sanitized, and non-executing. **Files Changed**: * `apps/cli/tests/orchestrationDiagnostics.test.js` - added isolation diagnostics fetch and compaction tests. * `apps/cli/tests/cliRuntime.test.js` - added status/doctor isolation output fixture coverage. * `apps/hooks/tests/orchestrationDiagnostics.test.js` - added inbound execution-shaped diagnostic summary coverage. **BQC Fixes**: * External dependency resilience: CLI tests cover local-only request boundaries. * Error information boundaries: CLI and hook tests assert raw prompts, paths, and tokens are not surfaced. * Trust boundary enforcement: hook test keeps inbound command-shaped frames as diagnostics, not execution. *** ### Task T022 - Run focused verification gates **Started**: 2026-05-30 06:10 **Completed**: 2026-05-30 06:18 **Duration**: 8 minutes **Notes**: * Ran focused Vitest suites for protocol, server, CLI, and hooks. Final result: 8 test files passed, 38 tests passed. * Ran TypeScript checks for `packages/protocol` and `apps/server`. * Ran focused Biome format and lint checks for changed TypeScript and JavaScript files. * Ran ASCII, LF, and `git diff --check` hygiene gates for touched session files. * Fixed one protocol typecheck issue by giving the compact unsupported status map an explicit `Partial>` type. * Fixed one overly broad server test assertion so the redaction category label `proposal_rationale` remains allowed while raw proposal text remains blocked. **Files Changed**: * `packages/protocol/src/rest.ts` - tightened status map typing. * `apps/server/tests/isolationDiagnostics.test.ts` - narrowed raw-payload assertion. * `.spec_system/specs/phase06-session05-isolation-boundary-and-sandbox-diagnostics/implementation-notes.md` - recorded verification results. * `.spec_system/specs/phase06-session05-isolation-boundary-and-sandbox-diagnostics/tasks.md` - marked verification task complete. **Verification Results**: * [x] `npx vitest run packages/protocol/tests/isolation.test.ts packages/protocol/tests/rest.test.ts apps/server/tests/isolationDiagnostics.test.ts apps/server/tests/unsupportedRoutes.test.ts apps/server/tests/guardedActions.test.ts apps/cli/tests/orchestrationDiagnostics.test.js apps/cli/tests/cliRuntime.test.js apps/hooks/tests/orchestrationDiagnostics.test.js` * [x] `npm --workspace packages/protocol run typecheck` * [x] `npm --workspace apps/server run typecheck` * [x] `npx biome format ...changed code/test files` * [x] `npx biome lint ...changed code/test files` * [x] ASCII check for touched session files * [x] LF check for touched session files * [x] `git diff --check -- ...touched session files` *** --- # 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/implementation-notes.md?ask=&goal= ``` `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.