> 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-session03-cli-lifecycle-parity/tasks.md).

# Task Checklist

**Session ID**: `phase01-session03-cli-lifecycle-parity` **Total Tasks**: 21 **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        | 4      | 4      | 0         |
| **Total**      | **21** | **21** | **0**     |

***

## Setup (3 tasks)

Initial configuration and environment preparation.

### apps/cli

* [x] T001 \[S0103] Verify current CLI command surface, workspace launch scripts, and original CLI parity gaps (`apps/cli/src/index.js`)
* [x] T002 \[S0103] Create lifecycle fixture test scaffold for PID, port, workspace, process, and browser behavior (`apps/cli/tests/lifecycle.test.js`)

### apps/hooks

* [x] T003 \[S0103] Create hook install/uninstall fixture test scaffold for backup, merge, malformed settings, and managed-entry removal (`apps/hooks/tests/installScripts.test.js`)

***

## Foundation (5 tasks)

Core structures and base implementations.

### apps/cli

* [x] T004 \[S0103] \[P] Extend local file helpers with PID, project-root, config, stale cleanup, and atomic write helpers with idempotency protection (`apps/cli/src/lib/localFiles.js`)
* [x] T005 \[S0103] \[P] Create lifecycle helper for runtime-root discovery, port normalization, health probes, managed process state, and signal cleanup on scope exit (`apps/cli/src/lib/lifecycle.js`)
* [x] T006 \[S0103] \[P] Create platform browser opener helper with timeout, fallback URL output, and failure-path handling (`apps/cli/src/lib/browser.js`)

### apps/hooks

* [x] T007 \[S0103] \[P] Harden hook install script with safe JSON parsing, backup preservation, managed-entry replacement, and atomic settings writes (`apps/hooks/scripts/install.js`)
* [x] T008 \[S0103] \[P] Harden hook uninstall script with backup restore, managed-entry-only removal, malformed-file handling, and atomic settings writes (`apps/hooks/scripts/uninstall.js`)

***

## Implementation (9 tasks)

Main feature implementation.

### apps/cli

* [x] T009 \[S0103] Implement `start` and `launch` command behavior with duplicate-trigger prevention while in-flight and bounded foreground/daemon lifecycle handling (`apps/cli/src/commands/start.js`)
* [x] T010 \[S0103] Implement `stop` command behavior with PID validation, stale-state cleanup, bounded SIGTERM/SIGKILL handling, and unrelated-process protection (`apps/cli/src/commands/stop.js`)
* [x] T011 \[S0103] Implement `open` command behavior with server reachability checks, browser fallback, and clear manual URL output (`apps/cli/src/commands/open.js`)
* [x] T012 \[S0103] Wire command dispatch, `install` alias, `launch` alias, flag parsing, help text, and unknown-command messaging (`apps/cli/src/index.js`)
* [x] T013 \[S0103] Extend status output with managed PID, configured port, workspace root, lifecycle state, stale PID reporting, and sanitized diagnostics (`apps/cli/src/commands/status.js`)
* [x] T014 \[S0103] Extend doctor output with Node version, current-workspace script checks, port checks, PID checks, hook install state, listener state, and sanitized hints (`apps/cli/src/commands/doctor.js`)
* [x] T015 \[S0103] Update init success guidance to reference supported lifecycle commands and current workspace launch boundaries (`apps/cli/src/commands/init.js`)
* [x] T016 \[S0103] Update CLI package metadata if new command or helper files need package inclusion and command docs alignment (`apps/cli/package.json`)

### Documentation

* [x] T017 \[S0103] Update CLI, hook, root, and privacy docs for lifecycle commands, PID files, port behavior, workspace root, hook safety, and deferred publish scope (`apps/cli/README_cli.md`)

***

## Testing (4 tasks)

Verification and quality assurance.

### apps/cli

* [x] T018 \[S0103] Fill lifecycle tests for start, daemon duplicate prevention, stop, open, stale PID cleanup, port parsing, and workspace-root persistence (`apps/cli/tests/lifecycle.test.js`)
* [x] T019 \[S0103] Extend CLI runtime tests for install/init alias behavior, status output, doctor output, and sanitized fixture diagnostics (`apps/cli/tests/cliRuntime.test.js`)

### apps/hooks

* [x] T020 \[S0103] Fill hook install/uninstall fixture tests for backup creation, malformed settings, managed replacement, restore, surgical removal, and temp-file cleanup (`apps/hooks/tests/installScripts.test.js`)

### Validation

* [x] T021 \[S0103] Run focused CLI/hook tests, Biome lint on touched files, and ASCII/LF checks, then record results (`.spec_system/specs/phase01-session03-cli-lifecycle-parity/implementation-notes.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 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/phase01-session03-cli-lifecycle-parity/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.