> 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/phase03-session04-guarded-local-action-runtime/implementation-notes.md). # Implementation Notes **Session ID**: `phase03-session04-guarded-local-action-runtime` **Package**: Cross-cutting (`packages/protocol`, `apps/server`, `apps/cli`) **Started**: 2026-05-29 12:50 **Last Updated**: 2026-05-29 12:50 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 24 / 24 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### 2026-05-29 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Local npm workspace tools available through `node_modules/.bin` * [x] Directory structure ready * [x] Database not applicable *** ### Task T001 - Verify prerequisites and owner rows **Started**: 2026-05-29 12:49 **Completed**: 2026-05-29 12:50 **Duration**: 1 minute **Notes**: * Ran deterministic project analysis and confirmed current session `phase03-session04-guarded-local-action-runtime`. * Confirmed completed Session 01, 02, and 03 dependencies in `.spec_system/state.json` and prior implementation summaries. * Reviewed Session 04 owner rows in the Phase 03 orchestration gap matrix for guarded-action lifecycle, file, git, terminal, remote/container, and approval-bridge boundaries. **Files Changed**: * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/implementation-notes.md` - initialized session implementation log. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T001 complete and updated progress. **BQC Fixes**: * N/A - prerequisites and artifact setup only. *** ### Task T002 - Create implementation and security artifacts **Started**: 2026-05-29 12:50 **Completed**: 2026-05-29 12:50 **Duration**: 1 minute **Notes**: * Created the implementation notes file with environment verification, progress tracking, and task log sections. * Created the session security and compliance artifact with initial local-first, in-memory, and fail-closed posture. **Files Changed**: * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/implementation-notes.md` - added T002 progress entry. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/security-compliance.md` - initialized session security artifact. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T002 complete and updated progress. **BQC Fixes**: * N/A - artifact setup only. *** ### Task T003 - Confirm unsupported routes, WebSocket approval, and CLI helper baselines **Started**: 2026-05-29 12:50 **Completed**: 2026-05-29 12:51 **Duration**: 1 minute **Notes**: * Confirmed unsupported route classification keeps file, git, terminal, remote-access, container, settings, task-queue, webhook, push, and collaboration families deterministic 501 responses. * Confirmed WebSocket approval handling validates client messages, suppresses duplicate permission and plan decisions per socket lifecycle, and emits compact response frames. * Confirmed CLI helper patterns use local settings, loopback defaults, bounded health probes, auth token forwarding, and sanitized local diagnostics. **Files Changed**: * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/implementation-notes.md` - added T003 baseline record. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T003 complete and updated progress. **BQC Fixes**: * N/A - baseline review only. *** ### Task T004 - Create guarded-action domain contracts **Started**: 2026-05-29 12:51 **Completed**: 2026-05-29 12:54 **Duration**: 3 minutes **Notes**: * Added protocol-owned guarded-action family, kind, state, decision, execution result, unavailable reason, failure code, risk, proposal, snapshot, mutation, and compact event proposal contracts. * Kept the event proposal shape compact so broad WebSocket updates can avoid raw rationale, command bodies, file contents, terminal output, and paths. **Files Changed**: * `packages/protocol/src/guardedActions.ts` - created guarded-action domain contracts. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T004 complete and updated progress. **BQC Fixes**: * Contract alignment: separated proposal details from compact event summaries to prevent broad event payload drift. *** ### Task T005 - Add guarded-action REST contracts **Started**: 2026-05-29 12:54 **Completed**: 2026-05-29 12:54 **Duration**: 1 minute **Notes**: * Added guarded-action create, decision, list, detail, and mutation REST aliases. * Added `guarded-actions` to the shared route-family vocabulary for route capability and unsupported-route classification alignment. **Files Changed**: * `packages/protocol/src/rest.ts` - added guarded-action REST contracts and route family. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T005 complete and updated progress. **BQC Fixes**: * Contract alignment: REST aliases now point to protocol-owned guarded-action shapes. *** ### Task T006 - Add guarded-action WebSocket contracts **Started**: 2026-05-29 12:54 **Completed**: 2026-05-29 12:55 **Duration**: 1 minute **Notes**: * Added `guarded_action_update` server frames with counts, compact proposals, generated timestamp, and optional change metadata. * Added `guarded_action_decision` client messages with action ID, approved boolean, reason, expected revision, and idempotency key. **Files Changed**: * `packages/protocol/src/events.ts` - added guarded-action server event and client decision message contracts. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T006 complete and updated progress. **BQC Fixes**: * Contract alignment: client and server WebSocket discriminants now use protocol-owned payloads. *** ### Task T007 - Export guarded-action contracts **Started**: 2026-05-29 12:55 **Completed**: 2026-05-29 12:55 **Duration**: 1 minute **Notes**: * Exported guarded-action contracts from the protocol package root so server, CLI tests, and future web code can import them from `@factionos/protocol`. **Files Changed**: * `packages/protocol/src/index.ts` - exported `guardedActions`. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T007 complete and updated progress. **BQC Fixes**: * Contract alignment: package root now exposes the same contracts used by REST and WebSocket types. *** ### Task T008 - Create guarded-action validation helpers **Started**: 2026-05-29 12:55 **Completed**: 2026-05-29 12:59 **Duration**: 4 minutes **Notes**: * Added schema-style request parsers for guarded-action list, create, decision, and route IDs. * Validates family/kind alignment, bounded strings, preview metadata, references, expiration windows, booleans, revision integers, and idempotency keys. * Errors use compact `invalid_request` envelopes and do not echo request payloads. **Files Changed**: * `apps/server/src/lib/guardedActionValidation.ts` - created guarded-action validation helpers. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T008 complete and updated progress. **BQC Fixes**: * Trust boundary enforcement: guarded-action inputs are validated at the route boundary before manager mutation. * Failure path completeness: malformed request bodies map to compact validation responses. *** ### Task T009 - Create bounded guarded-action manager **Started**: 2026-05-29 12:59 **Completed**: 2026-05-29 13:03 **Duration**: 4 minutes **Notes**: * Added an in-memory guarded-action manager with a 200-proposal cap, create idempotency, decision idempotency, mutation locks, stale revision checks, expiration on read/decision paths, deterministic ordering, and compact event summaries. * Approved proposals fail closed to an explicit unavailable execution result when no safe local executor is available. * Proposal text and preview text pass through existing sensitive-text redaction before storage and response. **Files Changed**: * `apps/server/src/managers/guardedActions.ts` - created guarded-action manager. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T009 complete and updated progress. **BQC Fixes**: * Duplicate action prevention: create and decision idempotency keys plus mutation locks guard repeated triggers. * State freshness on re-entry: pending proposals expire during list, detail, and decision paths. * Error information boundaries: manager errors use stable messages and compact details. *** ### Task T010 - Create guarded-action CLI HTTP helper **Started**: 2026-05-29 13:03 **Completed**: 2026-05-29 13:05 **Duration**: 2 minutes **Notes**: * Added local-only CLI helper APIs for guarded-action create, list, detail, decision, approve, and reject calls. * Helper reads configured local server URL, rejects non-loopback URLs, forwards bearer auth when configured, applies bounded timeouts, retries transient failures with short backoff, and returns sanitized compact errors. **Files Changed**: * `apps/cli/src/lib/guardedActions.js` - created guarded-action HTTP helper. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T010 complete and updated progress. **BQC Fixes**: * External dependency resilience: local HTTP calls have timeout and retry/backoff behavior. * Error information boundaries: helper sanitizes error messages and compact response fields. * Failure path completeness: helper returns structured failures for invalid URLs, non-loopback URLs, invalid JSON, timeout, and unreachable server states. *** ### Task T011 - Add guarded-action proposal, list, and detail routes **Started**: 2026-05-29 13:05 **Completed**: 2026-05-29 13:08 **Duration**: 3 minutes **Notes**: * Added guarded-action REST routes for proposal creation, listing, and detail lookup. * List routes use bounded pagination and validated state/family filters; manager ordering remains deterministic. * Read paths expire pending proposals before returning state and emit compact update frames for expirations. **Files Changed**: * `apps/server/src/routes/guardedActions.ts` - created guarded-action REST route module. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T011 complete and updated progress. **BQC Fixes**: * State freshness on re-entry: list and detail routes expire stale pending proposals before response. * Trust boundary enforcement: route inputs pass through guarded-action validators before manager calls. *** ### Task T012 - Add guarded-action approve and reject routes **Started**: 2026-05-29 13:08 **Completed**: 2026-05-29 13:09 **Duration**: 1 minute **Notes**: * Added `/guarded-actions/:id/approve`, `/guarded-actions/:id/reject`, and generic `/guarded-actions/:id/decision` routes. * Routes use per-action in-flight mutation guards, revision validation, idempotency fields, and manager-level expiration revalidation before decisions. **Files Changed**: * `apps/server/src/routes/guardedActions.ts` - added decision routes and mutation conflict handling. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T012 complete and updated progress. **BQC Fixes**: * Duplicate action prevention: route-level in-flight guards prevent concurrent decision mutations. * Concurrency safety: manager-level locks remain the final guard for duplicate decision paths. *** ### Task T013 - Add unavailable execution-result handling **Started**: 2026-05-29 13:09 **Completed**: 2026-05-29 13:09 **Duration**: 1 minute **Notes**: * Approved guarded actions now transition through an explicit user decision to an unavailable execution result when no safe local executor exists. * Remote-access and container families are mapped to policy-blocked unavailable results; local file, git, terminal, subagent, mission, and handoff kinds map to not-implemented unavailable results. * No filesystem, git, terminal, remote, or container side effects are performed. **Files Changed**: * `apps/server/src/managers/guardedActions.ts` - added fail-closed unavailable execution-result behavior. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T013 complete and updated progress. **BQC Fixes**: * Failure path completeness: approved-but-unexecutable actions return explicit unavailable result state. * External dependency resilience: absent local executors are represented as state, not hidden retries or side effects. *** ### Task T014 - Wire guarded-action manager and routes into server **Started**: 2026-05-29 13:09 **Completed**: 2026-05-29 13:10 **Duration**: 1 minute **Notes**: * Instantiated the guarded-action manager in server composition and registered guarded-action routes after existing auth, CORS, rate-limit, and body-size middleware. * Passed the same manager into WebSocket handler context for decision messages. * Did not alter bind, auth, CORS, Origin, rate-limit, or JSON body-size defaults. **Files Changed**: * `apps/server/src/server.ts` - wired guarded-action manager, routes, and WebSocket dependency. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T014 complete and updated progress. **BQC Fixes**: * Trust boundary enforcement: new routes inherit existing auth and middleware stack before mutation. *** ### Task T015 - Add guarded-action WebSocket decision validation and handling **Started**: 2026-05-29 13:10 **Completed**: 2026-05-29 13:11 **Duration**: 1 minute **Notes**: * Added validation for `guarded_action_decision` WebSocket client messages with bounded action IDs, booleans, reasons, revisions, and idempotency keys. * Added handler support that suppresses duplicate decisions from the same socket lifecycle, delegates to the guarded-action manager, emits compact update frames, and returns compact toast failures. **Files Changed**: * `apps/server/src/ws/clientMessageValidation.ts` - added guarded-action decision validation. * `apps/server/src/ws/handlers.ts` - added guarded-action decision handling. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T015 complete and updated progress. **BQC Fixes**: * Duplicate action prevention: socket-level handled action keys suppress repeat decision messages. * Error information boundaries: WebSocket failures return stable toast messages without raw request echo. *** ### Task T016 - Preserve unsupported route families **Started**: 2026-05-29 13:11 **Completed**: 2026-05-29 13:11 **Duration**: 1 minute **Notes**: * Confirmed guarded-action endpoints are additive and do not remove file, git, terminal, remote-access, or container route prefixes from unsupported classification. * Existing unapproved historical route families remain deterministic 501 capability responses. **Files Changed**: * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/implementation-notes.md` - recorded unsupported-route preservation. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T016 complete and updated progress. **BQC Fixes**: * Failure path completeness: out-of-scope historical routes still fail closed with deterministic capability responses. *** ### Task T017 - Expose safe local guarded-action helper APIs **Started**: 2026-05-29 13:11 **Completed**: 2026-05-29 13:12 **Duration**: 1 minute **Notes**: * Exposed helper-level proposal, list, detail, approve, reject, and generic decision APIs from `apps/cli/src/lib/guardedActions.js`. * Did not add user-facing CLI commands or any remote execution controls. **Files Changed**: * `apps/cli/src/lib/guardedActions.js` - exposed guarded-action helper API functions. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T017 complete and updated progress. **BQC Fixes**: * Trust boundary enforcement: helper rejects non-loopback server URLs before making guarded-action requests. *** ### Task T018 - Update concise guarded-action API docs **Started**: 2026-05-29 13:12 **Completed**: 2026-05-29 13:15 **Duration**: 3 minutes **Notes**: * Documented guarded-action REST routes, WebSocket decision messages, update frames, unavailable approval results, and local-only non-execution boundaries in the concise API reference. **Files Changed**: * `docs/api/README_api.md` - added guarded-action route and WebSocket documentation. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T018 complete and updated progress. **BQC Fixes**: * Contract alignment: docs now match shipped guarded-action protocol, route, and WebSocket names. *** ### Task T019 - Update source-backed guarded-action contract docs **Started**: 2026-05-29 13:15 **Completed**: 2026-05-29 13:16 **Duration**: 1 minute **Notes**: * Updated the source-backed API and WebSocket contract document with guarded-action route statuses, decision lifecycle behavior, conflict behavior, event frame production, and deferred file/git/terminal/remote/container boundaries. **Files Changed**: * `docs/api/event-api-hook-contracts.md` - added guarded-action route, WebSocket, and Phase 03 contract details. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T019 complete and updated progress. **BQC Fixes**: * Contract alignment: source-backed docs now distinguish shipped proposal/decision state from deferred execution. *** ### Task T020 - Write protocol guarded-action contract tests **Started**: 2026-05-29 13:16 **Completed**: 2026-05-29 13:20 **Duration**: 4 minutes **Notes**: * Added protocol tests for guarded-action vocabularies, REST request and response aliases, compact WebSocket update frames, client decision messages, and route-family discriminants. **Files Changed**: * `packages/protocol/tests/guardedActions.test.ts` - added guarded-action protocol contract tests. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T020 complete and updated progress. **BQC Fixes**: * Contract alignment: tests assert compact event frames omit rationale, preview, and command-like fields. *** ### Task T021 - Write server guarded-action route and manager tests **Started**: 2026-05-29 13:20 **Completed**: 2026-05-29 13:22 **Duration**: 2 minutes **Notes**: * Added server tests for guarded-action create, idempotent create, detail, approve, duplicate decision, reject conflict, filtered list, compact validation errors, manager expiration, and policy-blocked unavailable container behavior. **Files Changed**: * `apps/server/tests/guardedActions.test.ts` - added guarded-action route and manager tests. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T021 complete and updated progress. **BQC Fixes**: * Duplicate action prevention: tests cover idempotent create and decision behavior. * State freshness on re-entry: tests cover manager expiration. * Error information boundaries: tests assert raw sensitive fields are not echoed. *** ### Task T022 - Write WebSocket, auth-boundary, and unsupported-route tests **Started**: 2026-05-29 13:22 **Completed**: 2026-05-29 13:24 **Duration**: 2 minutes **Notes**: * Added WebSocket coverage for guarded-action update frames and duplicate socket decision suppression. * Added auth-boundary coverage proving guarded-action mutation routes inherit bearer auth before validation. * Expanded unsupported-route tests for remote-access and container paths staying deterministic 501 responses. **Files Changed**: * `apps/server/tests/websocket.test.ts` - added guarded-action WebSocket decision coverage. * `apps/server/tests/authBoundaries.test.ts` - added guarded-action auth coverage. * `apps/server/tests/unsupportedRoutes.test.ts` - added remote/container route classification checks. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T022 complete and updated progress. **BQC Fixes**: * Trust boundary enforcement: tests verify auth precedes guarded-action validation and mutation. * Failure path completeness: tests verify deferred remote/container paths remain fail-closed. *** ### Task T023 - Write CLI guarded-action helper tests **Started**: 2026-05-29 13:24 **Completed**: 2026-05-29 13:25 **Duration**: 1 minute **Notes**: * Added CLI helper tests for bearer auth forwarding, JSON body handling, compact error parsing, sensitive output sanitization, retry/backoff on transient failures, timeout handling, and non-loopback URL rejection. **Files Changed**: * `apps/cli/tests/guardedActions.test.js` - added guarded-action helper tests. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T023 complete and updated progress. **BQC Fixes**: * External dependency resilience: tests cover retry/backoff and timeout failure paths. * Error information boundaries: tests cover sanitized compact error output. *** ### Task T024 - Run focused checks and patch hygiene **Started**: 2026-05-29 13:25 **Completed**: 2026-05-29 13:31 **Duration**: 6 minutes **Notes**: * Ran focused protocol and server typechecks. * Ran focused protocol, server, WebSocket, auth-boundary, unsupported-route, and CLI helper tests. * Ran Biome check for touched JS/TS files. * Ran ASCII, LF, and `git diff --check` patch hygiene checks. * Fixed one server route type narrowing issue and tightened CLI nested error-field sanitization after the first focused test pass exposed them. **Files Changed**: * `apps/server/src/routes/guardedActions.ts` - tightened request body record narrowing. * `apps/cli/src/lib/guardedActions.js` - redacts nested compact error fields by key. * `packages/protocol/tests/guardedActions.test.ts` - adjusted compact-frame assertion to avoid matching enum vocabulary. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/implementation-notes.md` - recorded check results. * `.spec_system/specs/phase03-session04-guarded-local-action-runtime/tasks.md` - marked T024 complete and updated completion checklist. **Validation Results**: * `npm --workspace packages/protocol run typecheck` - pass. * `npm --workspace apps/server run typecheck` - pass. * `npx vitest run packages/protocol/tests/guardedActions.test.ts apps/server/tests/guardedActions.test.ts apps/server/tests/websocket.test.ts apps/server/tests/authBoundaries.test.ts apps/server/tests/unsupportedRoutes.test.ts apps/cli/tests/guardedActions.test.js` - pass, 28 tests. * `npx biome check` on touched JS/TS files - pass. * `git diff --check` - pass. * ASCII check for touched files - pass. * LF check for touched files - pass. **BQC Fixes**: * Error information boundaries: nested compact CLI error fields now redact by field key. * Contract alignment: protocol tests now assert compact event shape without rejecting valid guarded-action enum discriminants. *** ## Session Completion Session implementation complete. Tasks: 24 / 24 (100%). BQC: fixes or checks recorded across application-code implementation and testing tasks. Next workflow step: run `validate` to verify session completeness. --- # 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/phase03-session04-guarded-local-action-runtime/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.