> 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/phases/phase_03/session_04_guarded_local_action_runtime.md).

# Session 04: Guarded Local Action Runtime

**Session ID**: `phase03-session04-guarded-local-action-runtime` **Packages**: packages/protocol, apps/server, apps/cli **Status**: Not Started **Estimated Tasks**: \~18-24 **Estimated Duration**: 2-4 hours

***

## Objective

Implement the local runtime contract for guarded orchestration actions such as spawn, resume, stop, fork, handoff, and approved file, git, or terminal proposals.

***

## Scope

### In Scope (MVP)

* Define action proposal, approval, rejection, expiration, execution-result, and unavailable-state contracts.
* Implement local server handling for approved Phase 03 action families with validation and explicit permission boundaries.
* Add CLI-side helpers only for safe local lifecycle or diagnostic actions approved by Session 01.
* Preserve deterministic unsupported responses for action families that remain out of scope.
* Test duplicate approvals, expired actions, auth failure, non-loopback guardrails, command redaction, and unavailable local dependencies.

### Out of Scope

* Hidden or automatic remote command execution.
* Inbound chat or webhook commands.
* Docker/container isolation routes unless Session 01 explicitly keeps them deferred.
* Web UI controls beyond contract support.

***

## Prerequisites

* [ ] Session 01 safety model defines allowed and deferred action families.
* [ ] Session 02 queue/template contracts are available for queue-driven action references.
* [ ] Session 03 lineage contracts are available for subagent-related action references.

***

## Deliverables

1. Protocol guarded-action contracts.
2. Local server route and WebSocket handling for approved action lifecycles.
3. CLI helper updates for approved local diagnostics or lifecycle actions.
4. Focused security, validation, and duplicate-response tests.

***

## Success Criteria

* [ ] Every mutating orchestration action has an explicit pending, accepted, rejected, expired, failed, or unavailable state.
* [ ] Dangerous or unsupported actions fail closed with compact, redacted responses.
* [ ] Existing local-server authorization, Origin, CORS, rate-limit, and body-size protections still apply.


---

# 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/phases/phase_03/session_04_guarded_local_action_runtime.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.