> 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/tasks.md).

# Task Checklist

**Session ID**: `phase03-session04-guarded-local-action-runtime` **Total Tasks**: 24 **Estimated Duration**: 3-4 hours **Created**: 2026-05-29

***

## Legend

* `[x]` = Completed
* `[ ]` = Pending
* `[P]` = Parallelizable (can run with other \[P] tasks)
* `[SNNMM]` = Session reference (NN=phase number, MM=session number)
* `TNNN` = Task ID

***

## Progress Summary

| Category       | Total  | Done   | Remaining |
| -------------- | ------ | ------ | --------- |
| Setup          | 3      | 3      | 0         |
| Foundation     | 7      | 7      | 0         |
| Implementation | 9      | 9      | 0         |
| Testing        | 5      | 5      | 0         |
| **Total**      | **24** | **24** | **0**     |

***

## Setup (3 tasks)

Initial configuration and environment preparation.

### Cross-package

* [x] T001 \[S0304] Verify Session 04 prerequisites, completed Session 01/02/03 dependencies, and guarded-action owner rows (`.spec_system/PRD/phase_03/orchestration_gap_matrix.md`)
* [x] T002 \[S0304] Create implementation notes and security artifact placeholders (`.spec_system/specs/phase03-session04-guarded-local-action-runtime/implementation-notes.md`)
* [x] T003 \[S0304] Confirm current unsupported file/git/terminal route baseline, WebSocket approval baseline, and CLI helper patterns (`apps/server/src/lib/unsupportedRoutes.ts`)

***

## Foundation (7 tasks)

Core structures and base implementations.

### packages/protocol

* [x] T004 \[S0304] \[P] Create guarded-action domain contracts with explicit proposal, decision, expiration, execution-result, failed, and unavailable states (`packages/protocol/src/guardedActions.ts`)
* [x] T005 \[S0304] Add guarded-action REST request and response contracts with schema-aligned compact error vocabulary (`packages/protocol/src/rest.ts`)
* [x] T006 \[S0304] Add guarded-action WebSocket event frames and client decision messages with types matching declared contract and exhaustive enum handling (`packages/protocol/src/events.ts`)
* [x] T007 \[S0304] Export guarded-action contracts from the protocol package root (`packages/protocol/src/index.ts`)

### apps/server

* [x] T008 \[S0304] \[P] Create guarded-action validation helpers with schema-validated input and explicit error mapping (`apps/server/src/lib/guardedActionValidation.ts`)
* [x] T009 \[S0304] \[P] Create bounded guarded-action manager with idempotency protection, expiration checks, duplicate-decision guards, and deterministic ordering (`apps/server/src/managers/guardedActions.ts`)

### apps/cli

* [x] T010 \[S0304] \[P] Create guarded-action HTTP helper with auth headers, timeout, retry/backoff, and failure-path handling (`apps/cli/src/lib/guardedActions.js`)

***

## Implementation (9 tasks)

Main feature implementation.

### apps/server

* [x] T011 \[S0304] Add guarded-action proposal, list, and detail routes with bounded pagination, validated filters, and deterministic ordering (`apps/server/src/routes/guardedActions.ts`)
* [x] T012 \[S0304] Add guarded-action approve and reject routes with duplicate-trigger prevention while in-flight, revision checks, and expiration revalidation (`apps/server/src/routes/guardedActions.ts`)
* [x] T013 \[S0304] Add execution-result and unavailable handling for approved action kinds with explicit failure mapping and no hidden file/git/terminal side effects (`apps/server/src/managers/guardedActions.ts`)
* [x] T014 \[S0304] Wire guarded-action manager and routes into server composition without changing auth, CORS, Origin, rate-limit, or body-size defaults (`apps/server/src/server.ts`)
* [x] T015 \[S0304] Add guarded-action WebSocket decision validation and handling with duplicate-trigger prevention while in-flight (`apps/server/src/ws/clientMessageValidation.ts`, `apps/server/src/ws/handlers.ts`)
* [x] T016 \[S0304] Preserve unapproved file, git, terminal, remote-access, and container paths as deterministic 501 capability responses (`apps/server/src/lib/unsupportedRoutes.ts`)

### apps/cli

* [x] T017 \[S0304] Expose safe local guarded-action proposal and decision helper APIs without adding user-facing remote execution commands (`apps/cli/src/lib/guardedActions.js`)

### docs/api

* [x] T018 \[S0304] Update concise API docs for guarded-action routes, WebSocket frames, unavailable states, and local-only boundaries (`docs/api/README_api.md`)
* [x] T019 \[S0304] Update source-backed contract docs for guarded-action route families, decision lifecycles, and deferred remote/container behavior (`docs/api/event-api-hook-contracts.md`)

***

## Testing (5 tasks)

Verification and quality assurance.

### packages/protocol

* [x] T020 \[S0304] \[P] Write protocol guarded-action contract tests for states, REST shapes, events, client messages, and exported discriminants (`packages/protocol/tests/guardedActions.test.ts`)

### apps/server

* [x] T021 \[S0304] \[P] Write server guarded-action route tests for create/list/detail/approve/reject, expiration, duplicate decisions, unavailable dependencies, and sensitive-field non-echo (`apps/server/tests/guardedActions.test.ts`)
* [x] T022 \[S0304] \[P] Write WebSocket, auth-boundary, and unsupported-route tests for guarded-action decisions and fail-closed route classification (`apps/server/tests/websocket.test.ts`, `apps/server/tests/authBoundaries.test.ts`, `apps/server/tests/unsupportedRoutes.test.ts`)

### apps/cli

* [x] T023 \[S0304] \[P] Write CLI guarded-action helper tests for auth headers, timeouts, retry/backoff, compact errors, and sanitized output (`apps/cli/tests/guardedActions.test.js`)

### Cross-package

* [x] T024 \[S0304] Run focused protocol, server, CLI, ASCII/LF, and patch hygiene checks and record results (`.spec_system/specs/phase03-session04-guarded-local-action-runtime/implementation-notes.md`)

***

## Completion Checklist

Before marking session complete:

* [x] All tasks marked `[x]`
* [x] Focused tests passing
* [x] All touched files ASCII-encoded
* [x] implementation-notes.md updated
* [x] security-compliance.md updated
* [x] Ready for the validate workflow step

***

## Next Steps

Run the validate workflow step 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/tasks.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.