> 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-session06-llm-fallback-and-scan-privacy/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase01-session06-llm-fallback-and-scan-privacy` **Package**: apps/server **Started**: 2026-05-29 05:47 **Last Updated**: 2026-05-29 06:18

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 22 / 22 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

## Session Source Map

### Session 05 Baseline

* `phase01-session05-websocket-hydration-and-archive-export-privacy/validation.md` passed with 24/24 tasks complete, 113 focused tests, server/web/protocol typechecks, Biome check, ASCII/LF checks, and no security findings.
* Session 05 added deterministic redaction helpers in `apps/server/src/lib/sessionPrivacy.ts`; Session 06 should reuse them instead of creating a parallel redaction policy.
* Session 05 explicitly deferred LLM provider-transfer controls to this session.

### LLM and Scan Expectations

* The current LLM route surface is `/llm/plan`, `/llm/analyze`, `/llm/scan-codebase`, `/llm/idle-suggestion`, `/memory`, and `/memory/:type`.
* The current no-key fallback path is deterministic through `apps/server/src/lib/llmClient.ts`.
* Current route validation is loose compared to the Session 04 `RequestValidator` envelope; this session should return compact `invalid_request` errors without raw payload echoes.
* Current codebase scanning ignores `EXAMPLES`, `findings`, generated artifact directories, symlinks, lockfiles, sourcemaps, and oversized files; this session adds route-level approved-root handling and redacted response metadata.
* Security findings M-002 and M-003 remain relevant: local memory retention is not unified under an erasure command, and provider-bound scans need explicit transfer controls before file contents can leave the local machine.

## Focused Verification Commands

* `npx vitest run apps/server/tests/llm.test.ts apps/server/tests/codebaseWalker.test.ts`
* `npm --workspace @factionos/server run typecheck`
* `npx biome check apps/server/src/lib/llmRequestValidation.ts apps/server/src/lib/llmPrivacy.ts apps/server/src/lib/llmClient.ts apps/server/src/llm/engines/onDemandAnalysis.ts apps/server/src/llm/engines/planDecomposer.ts apps/server/src/llm/engines/idleSuggestionEngine.ts apps/server/src/llm/engines/transcriptMiner.ts apps/server/src/routes/llm.ts apps/server/tests/llm.test.ts apps/server/tests/codebaseWalker.test.ts apps/server/README_server.md docs/api/README_api.md docs/api/event-api-hook-contracts.md docs/privacy-and-security.md`
* `git diff --check`
* ASCII/LF validation over touched files with `LC_ALL=C grep` and CRLF checks.
* Practical full gates after focused tests: `npm run typecheck`, `npm test`, and `npm run format:check` if time remains.

***

## Task Log

### 2026-05-29 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed with `check-prereqs.sh --json --env --package apps/server`
* [x] Directory structure ready
* [x] `node`, `npm`, `vitest`, and `biome` available through workspace tooling and `npx`
* [x] No database layer applies to this session

### Task T001 - Verify Session 05 completion, server LLM docs, and current route validation baseline

**Started**: 2026-05-29 05:47 **Completed**: 2026-05-29 05:48 **Duration**: 1 minute

**Notes**:

* Confirmed deterministic project state has Session 06 active for `apps/server`.
* Confirmed Session 05 validation result is PASS and its redaction helper is available for reuse.
* Confirmed existing LLM routes use ad hoc validation rather than the shared Session 04 invalid-request pattern.

**Files Changed**:

* `.spec_system/specs/phase01-session06-llm-fallback-and-scan-privacy/implementation-notes.md` - created baseline implementation log.

**BQC Fixes**:

* N/A - context and baseline only.

### Task T002 - Map LLM fallback, provider-transfer, scan, and memory privacy expectations into implementation notes

**Started**: 2026-05-29 05:48 **Completed**: 2026-05-29 05:49 **Duration**: 1 minute

**Notes**:

* Mapped no-key fallback, provider-transfer opt-in, approved scan roots, redacted scan responses, and memory route exposure expectations.
* Captured M-002 and M-003 as retained security context for implementation and docs.

**Files Changed**:

* `.spec_system/specs/phase01-session06-llm-fallback-and-scan-privacy/implementation-notes.md` - added session source map.

**BQC Fixes**:

* N/A - context and documentation mapping only.

### Task T003 - Identify focused server verification commands before code changes

**Started**: 2026-05-29 05:49 **Completed**: 2026-05-29 05:49 **Duration**: 1 minute

**Notes**:

* Recorded focused Vitest, server typecheck, Biome, diff, ASCII, LF, and practical full-gate commands before code changes.

**Files Changed**:

* `.spec_system/specs/phase01-session06-llm-fallback-and-scan-privacy/implementation-notes.md` - added focused verification command list.

**BQC Fixes**:

* N/A - verification planning only.

### Task T004 - Create LLM request validation helper with schema-validated input and compact no-echo errors

**Started**: 2026-05-29 05:50 **Completed**: 2026-05-29 05:55 **Duration**: 5 minutes

**Notes**:

* Added typed validators for plan, analyze, scan, and idle-suggestion route bodies.
* Validation rejects non-object bodies, malformed file entries, oversized arrays, invalid scan limits, and invalid extensions through the shared `invalid_request` envelope.

**Files Changed**:

* `apps/server/src/lib/llmRequestValidation.ts` - created route-body validation helpers.

**BQC Fixes**:

* Trust boundary enforcement: LLM route bodies now enter route handlers as parsed typed values.
* Error information boundaries: validation responses include field names and compact rules, not raw payload content.

### Task T005 - Create LLM privacy helper for provider-transfer state, approved scan roots, and deterministic text redaction

**Started**: 2026-05-29 05:50 **Completed**: 2026-05-29 05:55 **Duration**: 5 minutes

**Notes**:

* Added provider-transfer state helpers for fallback, blocked-provider, and provider-enabled modes.
* Added approved scan root resolution using `process.cwd()` plus `FACTIONOS_SCAN_ROOTS`.
* Added memory, path, text, and scan-root redaction helpers.

**Files Changed**:

* `apps/server/src/lib/llmPrivacy.ts` - created provider-transfer, scan-root, and redaction helpers.

**BQC Fixes**:

* Trust boundary enforcement: scan roots must resolve under an approved directory before walking.
* Error information boundaries: scan-root failures map to compact reasons without echoing raw local paths.

### Task T006 - Add explicit provider-transfer opt-in and timeout fallback to LLM client

**Started**: 2026-05-29 05:55 **Completed**: 2026-05-29 05:58 **Duration**: 3 minutes

**Notes**:

* `ANTHROPIC_API_KEY` alone no longer triggers provider transfer; `FACTIONOS_ALLOW_LLM_PROVIDER_TRANSFER=true` is also required.
* Provider calls use redacted system/user text, a bounded timeout, and deterministic fallback on blocked, missing, failed, or timed-out calls.
* Server typecheck passed after the LLM client changes.

**Files Changed**:

* `apps/server/src/lib/llmClient.ts` - added provider gate, timeout, redacted inputs, and compact warnings.

**BQC Fixes**:

* External dependency resilience: provider calls have a timeout and fallback path.
* Error information boundaries: provider failures no longer log raw provider errors or local input data.

### Task T007 - Sanitize on-demand analysis prompt inputs and returned issue fields

**Started**: 2026-05-29 05:58 **Completed**: 2026-05-29 06:00 **Duration**: 2 minutes

**Notes**:

* File paths, file contents, anti-patterns, and returned issue fields now pass through LLM redaction before provider transfer or route return.

**Files Changed**:

* `apps/server/src/llm/engines/onDemandAnalysis.ts` - redacted provider-bound analysis text and returned issue fields.

**BQC Fixes**:

* Error information boundaries: issue fields and provider-bound prompts redact paths, URLs, tokens, and secret-like values.

### Task T008 - Sanitize plan, idle suggestion, and transcript-miner provider-bound inputs

**Started**: 2026-05-29 05:58 **Completed**: 2026-05-29 06:01 **Duration**: 3 minutes

**Notes**:

* Plan prompt/conventions, idle task/activity text, and transcript-miner context now pass through deterministic redaction before provider calls.
* Idle and transcript output fields are also redacted before return or persistence.

**Files Changed**:

* `apps/server/src/llm/engines/planDecomposer.ts` - redacted provider-bound plan prompt and conventions.
* `apps/server/src/llm/engines/idleSuggestionEngine.ts` - redacted provider-bound idle context and suggestion fields.
* `apps/server/src/llm/engines/transcriptMiner.ts` - redacted provider-bound transcript context and mined output fields.

**BQC Fixes**:

* Error information boundaries: prompt, transcript, URL, path, token, and command-like text is redacted before provider transfer.

### Task T009 - Redact memory finding route output while preserving type filtering

**Started**: 2026-05-29 06:01 **Completed**: 2026-05-29 06:02 **Duration**: 1 minute

**Notes**:

* `/memory` and `/memory/:type` now return redacted findings while preserving the `{ findings }` shape.
* Unsupported memory types now use the shared `invalid_request` envelope.

**Files Changed**:

* `apps/server/src/routes/llm.ts` - applied memory output redaction and compact type validation.

**BQC Fixes**:

* Error information boundaries: broad memory reads redact sensitive finding text and tags before returning JSON.

### Task T010 - Validate `/llm/plan` bodies through shared LLM request validation

**Started**: 2026-05-29 06:02 **Completed**: 2026-05-29 06:03 **Duration**: 1 minute

**Notes**:

* `/llm/plan` now validates prompt, optional mission ID, and conventions before calling `decomposePlan`.

**Files Changed**:

* `apps/server/src/routes/llm.ts` - wired plan route validation.

**BQC Fixes**:

* Trust boundary enforcement: plan route fields are validated and bounded before engine use.

### Task T011 - Validate `/llm/analyze` file arrays with caps and malformed-entry rejection

**Started**: 2026-05-29 06:02 **Completed**: 2026-05-29 06:03 **Duration**: 1 minute

**Notes**:

* `/llm/analyze` now rejects malformed file entries instead of silently dropping them.
* File count, path length, content length, and anti-pattern counts are bounded before analysis.

**Files Changed**:

* `apps/server/src/routes/llm.ts` - wired analyze route validation.
* `apps/server/src/lib/llmRequestValidation.ts` - owns analyze request parsing.

**BQC Fixes**:

* Trust boundary enforcement: caller-supplied file content is schema-validated before engine use.
* Failure path completeness: malformed file input gets an explicit 400 response.

### Task T012 - Validate `/llm/scan-codebase` root, limit, extensions, and anti-pattern options

**Started**: 2026-05-29 06:03 **Completed**: 2026-05-29 06:04 **Duration**: 1 minute

**Notes**:

* `/llm/scan-codebase` now validates scan options and requires the resolved root to be under `process.cwd()` or `FACTIONOS_SCAN_ROOTS`.

**Files Changed**:

* `apps/server/src/routes/llm.ts` - wired scan route validation and approved-root enforcement.
* `apps/server/src/lib/llmPrivacy.ts` - resolves approved scan roots.

**BQC Fixes**:

* Trust boundary enforcement: arbitrary local directories are no longer scannable unless explicitly approved.

### Task T013 - Redact scan progress events, scan metadata, and walker failure paths

**Started**: 2026-05-29 06:03 **Completed**: 2026-05-29 06:04 **Duration**: 1 minute

**Notes**:

* Scan progress events and response metadata now return redacted root placeholders instead of absolute local roots.
* Walker failures return compact validation details without raw filesystem error strings.

**Files Changed**:

* `apps/server/src/routes/llm.ts` - redacted scan events, root metadata, and error paths.

**BQC Fixes**:

* Error information boundaries: local roots and filesystem errors are not echoed in route responses or scan events.

### Task T014 - Validate `/llm/idle-suggestion` bodies with bounded fields

**Started**: 2026-05-29 06:04 **Completed**: 2026-05-29 06:04 **Duration**: 1 minute

**Notes**:

* `/llm/idle-suggestion` now validates hero ID and bounds optional task/activity context before engine use.

**Files Changed**:

* `apps/server/src/routes/llm.ts` - wired idle suggestion validation.
* `apps/server/src/lib/llmRequestValidation.ts` - owns idle request parsing.

**BQC Fixes**:

* Trust boundary enforcement: idle context is validated and bounded before provider/fallback use.

### Task T015 - Add provider privacy headers to LLM and memory routes

**Started**: 2026-05-29 06:04 **Completed**: 2026-05-29 06:05 **Duration**: 1 minute

**Notes**:

* All LLM and memory routes now include `X-FactionOS-LLM-Provider`, `X-FactionOS-LLM-Provider-Transfer`, and `X-FactionOS-LLM-Privacy`.
* Server typecheck passed with the route, helper, and engine changes.

**Files Changed**:

* `apps/server/src/routes/llm.ts` - added route-level provider privacy headers.

**BQC Fixes**:

* Failure path completeness: callers can inspect headers to distinguish fallback, blocked-provider, and enabled provider-transfer modes.

### Task T016 - Update server README with fallback, provider opt-in, scan allowlist, and memory retention behavior

**Started**: 2026-05-29 06:05 **Completed**: 2026-05-29 06:07 **Duration**: 2 minutes

**Notes**:

* Documented two-level Anthropic provider opt-in, provider privacy headers, timeout fallback, approved scan roots, redacted scan metadata, and redacted memory route output.

**Files Changed**:

* `apps/server/README_server.md` - updated LLM privacy and scan behavior.

**BQC Fixes**:

* N/A - documentation update only.

### Task T017 - Update API docs for hardened LLM routes, provider-transfer status, scan roots, and retained gaps

**Started**: 2026-05-29 06:07 **Completed**: 2026-05-29 06:08 **Duration**: 1 minute

**Notes**:

* Updated concise and detailed API docs for `invalid_request` behavior, provider-transfer headers, approved scan roots, redacted scan output, and redacted memory findings.

**Files Changed**:

* `docs/api/README_api.md` - updated LLM endpoint table and scan root notes.
* `docs/api/event-api-hook-contracts.md` - updated detailed route contracts and hardening status.

**BQC Fixes**:

* N/A - documentation update only.

### Task T018 - Update privacy docs for LLM provider transfer, scan content handling, memory exposure, and retained erasure limitations

**Started**: 2026-05-29 06:08 **Completed**: 2026-05-29 06:09 **Duration**: 1 minute

**Notes**:

* Updated privacy posture for explicit provider transfer, scan allowlists, redacted provider-bound text, memory route redaction, and remaining local retention/erasure risk.

**Files Changed**:

* `docs/privacy-and-security.md` - updated LLM and scan privacy controls and external-transfer matrix.

**BQC Fixes**:

* N/A - documentation update only.

### Task T019 - Extend LLM route tests for fallback, validation, provider-blocked, scan, and redaction behavior

**Started**: 2026-05-29 06:09 **Completed**: 2026-05-29 06:11 **Duration**: 2 minutes

**Notes**:

* Added route tests for blocked provider transfer, compact `invalid_request` errors, malformed analysis files, scan allowlist rejection, invalid scan options, redacted root metadata, provider headers, memory redaction, and provider-bound text redaction.
* Focused LLM and walker tests passed: 34 tests.

**Files Changed**:

* `apps/server/tests/llm.test.ts` - extended LLM route and privacy coverage.

**BQC Fixes**:

* Trust boundary enforcement: tests assert malformed route input is rejected before engine or walker use.
* Error information boundaries: tests assert raw temp roots and malformed file payload content are not echoed.

### Task T020 - Extend codebase walker tests for historical ignores, symlink avoidance, caps, and truncation

**Started**: 2026-05-29 06:09 **Completed**: 2026-05-29 06:11 **Duration**: 2 minutes

**Notes**:

* Extended walker tests to cover `historical-evidence`, `findings`, max file byte caps, and symlinked directory avoidance.
* Focused LLM and walker tests passed: 34 tests.

**Files Changed**:

* `apps/server/tests/codebaseWalker.test.ts` - extended walker privacy and cap coverage.

**BQC Fixes**:

* Resource cleanup: symlink test removes temporary outside directory after assertion.
* Trust boundary enforcement: tests assert symlinked external directories are skipped.

### Task T021 - Run focused server tests, server typecheck, Biome checks, ASCII validation, LF validation, and record results

**Started**: 2026-05-29 06:11 **Completed**: 2026-05-29 06:16 **Duration**: 5 minutes

**Notes**:

* Focused tests passed: `npx vitest run apps/server/tests/llm.test.ts apps/server/tests/codebaseWalker.test.ts` - 34 tests.
* Server typecheck passed: `npm --workspace @factionos/server run typecheck`.
* Focused Biome check passed for touched code, tests, and docs.
* `git diff --check` passed.
* ASCII and LF validation passed for touched files after removing pre-existing non-ASCII punctuation from touched files.

**Files Changed**:

* `.spec_system/specs/phase01-session06-llm-fallback-and-scan-privacy/implementation-notes.md` - recorded verification results.

**BQC Fixes**:

* N/A - verification task.

### Task T022 - Run full workspace quality/test gates that are practical locally and record pass/fail evidence

**Started**: 2026-05-29 06:16 **Completed**: 2026-05-29 06:18 **Duration**: 2 minutes

**Notes**:

* Workspace typecheck passed: `npm run typecheck`.
* Full Vitest passed: 96 files passed, 1 skipped; 1752 tests passed, 1 skipped.
* Format check passed: `npm run format:check` checked 287 files.
* `git diff --check` passed after full gates.

**Files Changed**:

* `.spec_system/specs/phase01-session06-llm-fallback-and-scan-privacy/implementation-notes.md` - recorded full-gate results.

**BQC Fixes**:

* N/A - verification task.


---

# 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-session06-llm-fallback-and-scan-privacy/implementation-notes.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.