> 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/phase01-session02-hook-runtime-safety/tasks.md).

# Task Checklist

**Session ID**: `phase01-session02-hook-runtime-safety` **Total Tasks**: 22 **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     | 5      | 5      | 0         |
| Implementation | 9      | 9      | 0         |
| Testing        | 5      | 5      | 0         |
| **Total**      | **22** | **22** | **0**     |

***

## Setup (3 tasks)

Initial context checks and test harness preparation.

### apps/hooks

* [x] T001 \[S0102] Verify Session 01 ingest contract outputs against current hook handlers and record retained assumptions (`docs/api/event-api-hook-contracts.md`)
* [x] T002 \[S0102] \[P] Create hook runtime process-test harness with temporary home, stdin, stdout, stderr, and unavailable-server controls (`apps/hooks/tests/hookRuntime.test.js`)

### apps/cli

* [x] T003 \[S0102] \[P] Add CLI JavaScript tests to the Vitest node project include list (`vitest.config.ts`)

***

## Foundation (5 tasks)

Shared safety primitives before handler changes.

### apps/hooks

* [x] T004 \[S0102] Add atomic text and JSON write helpers with temp-file cleanup on write failure (`apps/hooks/src/_lib.js`)
* [x] T005 \[S0102] Add shared session id path, safe tty name, and safe session read helpers with malformed-file fallback (`apps/hooks/src/_lib.js`)
* [x] T006 \[S0102] Add unavailable-server fallback posting helpers with bounded spool writes and no raw payload diagnostics (`apps/hooks/src/_lib.js`)
* [x] T007 \[S0102] Harden listener PID writes, reconnect timer cleanup, malformed frame handling, and bounded spool pump behavior with cleanup on scope exit for timers and sockets (`apps/hooks/src/ws-listener.js`)

### apps/cli

* [x] T008 \[S0102] \[P] Create CLI local file helpers for atomic JSON writes, safe JSON reads, and fixture-friendly home resolution (`apps/cli/src/lib/localFiles.js`)

***

## Implementation (9 tasks)

Runtime hardening across hooks, listener, CLI, and docs.

### apps/hooks

* [x] T009 \[S0102] Refactor hero spawn to use shared atomic session/PID helpers and duplicate-listener prevention while in-flight (`apps/hooks/src/factionos-hero-spawn.js`)
* [x] T010 \[S0102] Refactor prompt submit handler to use shared session resolution and fallback posting with duplicate-trigger prevention while in-flight (`apps/hooks/src/factionos-hero-active.js`)
* [x] T011 \[S0102] Refactor stop handler to use shared session resolution and fallback posting with missing-session fallback (`apps/hooks/src/factionos-hero-idle.js`)
* [x] T012 \[S0102] Refactor bash and file handlers to use shared session resolution, bounded previews, and fallback posting with schema-validated input and explicit error mapping (`apps/hooks/src/factionos-bash-command.js`, `apps/hooks/src/factionos-file-access.js`)
* [x] T013 \[S0102] Refactor input and permission handlers to use shared session resolution and bounded details with state reset or revalidation on re-entry (`apps/hooks/src/factionos-awaiting-input.js`, `apps/hooks/src/factionos-input-received.js`, `apps/hooks/src/factionos-permission-request.js`)
* [x] T014 \[S0102] Refactor subagent and git guard handlers to use shared session resolution while preserving restricted-mode stderr only for intentional denial (`apps/hooks/src/factionos-subagent-spawn.js`, `apps/hooks/src/factionos-subagent-complete.js`, `apps/hooks/src/factionos-git-guard.js`)

### apps/cli

* [x] T015 \[S0102] Wire CLI init settings and Claude settings writes through atomic local file helpers with malformed existing settings fallback (`apps/cli/src/commands/init.js`)
* [x] T016 \[S0102] Wire CLI doctor and status listener/spool diagnostics with bounded output, auth-aware probes, and explicit unavailable-server handling (`apps/cli/src/commands/doctor.js`, `apps/cli/src/commands/status.js`)

### Cross-package docs

* [x] T017 \[S0102] Update hook and CLI READMEs for diagnostics, latency limits, silence contract, listener behavior, and unavailable-server fallback (`apps/hooks/README_hooks.md`, `apps/cli/README_cli.md`)

***

## Testing (5 tasks)

Focused verification and quality gates.

### apps/hooks

* [x] T018 \[S0102] \[P] Write hook runtime tests for silent stdout/stderr, exit codes, unavailable server behavior, diagnostic log shape, and restricted git guard denial (`apps/hooks/tests/hookRuntime.test.js`)
* [x] T019 \[S0102] \[P] Write listener lifecycle tests for startup state, stale PID handling, malformed frames, bounded spool drain, and shutdown cleanup (`apps/hooks/tests/listenerRuntime.test.js`)

### apps/cli

* [x] T020 \[S0102] \[P] Write CLI runtime tests for init atomic writes, hook settings preservation, malformed settings fallback, and doctor/status diagnostics (`apps/cli/tests/cliRuntime.test.js`)

### Cross-package checks

* [x] T021 \[S0102] Run focused hook and CLI tests plus relevant workspace checks (`package.json`)
* [x] T022 \[S0102] Validate ASCII encoding, LF line endings, and manual unavailable-server hook behavior for touched files (`.spec_system/specs/phase01-session02-hook-runtime-safety/validation.md`)

***

## Completion Checklist

Before marking session complete:

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

***

## 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/phase01-session02-hook-runtime-safety/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.