> 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/phase18-session04-idle-lifecycle-engine-parity/tasks.md).

# Task Checklist

**Session ID**: `phase18-session04-idle-lifecycle-engine-parity` **Total Tasks**: 25 **Estimated Duration**: 3-4 hours **Created**: 2026-06-10

***

## 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     | 6      | 6      | 0         |
| Implementation | 11     | 11     | 0         |
| Testing        | 5      | 5      | 0         |
| **Total**      | **25** | **25** | **0**     |

***

## Setup (3 tasks)

Initial configuration and environment preparation.

* [x] T001 \[S1804] Verify Session 01-03 artifacts, idle lifecycle stub, and current server route/manager prerequisites (`.spec_system/PRD/phase_18/session_04_idle_lifecycle_engine_parity.md`)
* [x] T002 \[S1804] Verify current event ingest hero-idle transition and mission completion flow before wiring generation (`apps/server/src/routes/event.ts`)
* [x] T003 \[S1804] Verify current idle engine, LLM privacy boundary, and canned fallback mismatch before changing generation behavior (`apps/server/src/llm/engines/idleSuggestionEngine.ts`)

***

## Foundation (6 tasks)

Core structures and base implementations.

* [x] T004 \[S1804] \[P] Create pure idle suggestion context builder with bounded mission, hero, recent-message, and modified-file inputs with schema-validated input and explicit privacy filtering (`apps/server/src/lib/idleSuggestionContext.ts`)
* [x] T005 \[S1804] \[P] Create lifecycle coordinator types, options, clock injection, generation injection, and destroy contract with cleanup on scope exit for all acquired resources (`apps/server/src/lib/idleSuggestionLifecycle.ts`)
* [x] T006 \[S1804] Add recent session activity recording in the lifecycle coordinator with bounded per-session storage and state reset on destroy (`apps/server/src/lib/idleSuggestionLifecycle.ts`)
* [x] T007 \[S1804] Extend idle engine input and output types for typed suggestions while preserving the current route-compatible response shape (`apps/server/src/llm/engines/idleSuggestionEngine.ts`)
* [x] T008 \[S1804] Implement idle engine parser support for direct arrays, fenced arrays, extracted arrays, and fallback object `suggestions` arrays with explicit error mapping (`apps/server/src/llm/engines/idleSuggestionEngine.ts`)
* [x] T009 \[S1804] Implement deterministic fallback candidate builder from safe mission context and modified-file hints with types matching declared contract and generic-suggestion filtering (`apps/server/src/llm/engines/idleSuggestionEngine.ts`)

***

## Implementation (11 tasks)

Main feature implementation.

* [x] T010 \[S1804] Implement lifecycle idle trigger entry point keyed by stable session ID with duplicate-trigger prevention while in-flight (`apps/server/src/lib/idleSuggestionLifecycle.ts`)
* [x] T011 \[S1804] Implement 60-second per-session cooldown checks and test-injectable clock handling with deterministic ordering (`apps/server/src/lib/idleSuggestionLifecycle.ts`)
* [x] T012 \[S1804] Implement 18-second generation timeout and late-result suppression with cleanup on scope exit for all acquired timers/resources (`apps/server/src/lib/idleSuggestionLifecycle.ts`)
* [x] T013 \[S1804] Implement manager write path for generated idle suggestions through `SuggestionManager.createIdleSuggestion` with idempotency protection and failure-path handling (`apps/server/src/lib/idleSuggestionLifecycle.ts`)
* [x] T014 \[S1804] Wire generated manager mutations through `emitSuggestionMutationUpdate` so canonical snapshots and compatibility frames cannot drift (`apps/server/src/lib/idleSuggestionLifecycle.ts`)
* [x] T015 \[S1804] Wire lifecycle coordinator construction, dependency injection, and shutdown destroy ordering in the server runtime (`apps/server/src/server.ts`)
* [x] T016 \[S1804] Wire event route activity recording for relevant session events with bounded sanitized messages and no raw prompt or command leakage (`apps/server/src/routes/event.ts`)
* [x] T017 \[S1804] Trigger idle generation after the hero state is updated to `idle` in `/event` without blocking the HTTP response path (`apps/server/src/routes/event.ts`)
* [x] T018 \[S1804] Update `POST /llm/idle-suggestion` to call the upgraded engine and emit compatibility frames for returned suggestions without bypassing privacy headers (`apps/server/src/routes/llm.ts`)
* [x] T019 \[S1804] Add compact server warning behavior for generation failures without logging raw paths, prompts, transcripts, provider payloads, or secrets (`apps/server/src/lib/idleSuggestionLifecycle.ts`)
* [x] T020 \[S1804] Update server README with automatic idle lifecycle generation, fallback behavior, provider opt-in, and server-only scope (`apps/server/README_server.md`)

***

## Testing (5 tasks)

Verification and quality assurance.

* [x] T021 \[S1804] \[P] Write context-builder tests for mission data, modified-file extraction, sanitized recent messages, missing session ID, and unsafe path filtering (`apps/server/tests/idleSuggestionContext.test.ts`)
* [x] T022 \[S1804] \[P] Write lifecycle coordinator tests for trigger, cooldown, in-flight guard, timeout, destroy cleanup, fallback output, manager writes, and broadcasts (`apps/server/tests/idleSuggestionLifecycle.test.ts`)
* [x] T023 \[S1804] Write idle route and engine tests for typed fallback output, canned fallback object parsing, malformed output, generic filtering, and max 3 cap (`apps/server/tests/llm.test.ts`)
* [x] T024 \[S1804] Write route integration coverage for a full event lifecycle enqueueing typed Quest Board suggestions after idle transition (`apps/server/tests/routes.test.ts`)
* [x] T025 \[S1804] Run focused server Vitest files, server typecheck, and ASCII/LF validation for new session artifacts and touched server files (`apps/server/package.json`)

***

## 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/phase18-session04-idle-lifecycle-engine-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.