# Task: Implement PI-105 Pi Host API cutover

## Identity

- Task ID: 20260823-pi-host-cutover-c4e8a1d7
- Mode: Feature
- Branch: codex/20260823-pi-host-cutover-c4e8a1d7-pi-host-cutover
- Worktree: D:\Datas\OthersProjects\makelore-pi-host-cutover-c4e8a1d7
- Base commit: 7680bfb0cf206142a164b740d56f8be5ea59362a
- Owner: codex
- Status: Done

## Scope

- Implement `PI-105 — Files, changes, skills, and command Host API` from the
  `【架构】opencode2pi` Spec/ticket graph on cumulative PI-090 baseline
  `7680bfb0cf206142a164b740d56f8be5ea59362a`.
- Add a Main-owned vendor-neutral Project File Service for active-project
  status, find, bounded content and bounded text search.
- Add typed `/api/coding` routes for files, search, Conversation changes,
  managed Skills and the Conversation command catalog, plus the Renderer
  facade contract half owned by this ticket.
- Compose those routes with the same production `PiProductTools`, attachment
  store and `ConversationChangeTracker` instances used by the Pi extension.

## Intent And Constraints

- All file inputs are active-project-relative. Reject absolute, traversal and
  project-external paths; never project the absolute project root or expose an
  arbitrary filesystem proxy.
- Preserve the currently supported file/status/find/content/search UX while
  bounding file sizes, result counts and search output. Do not depend on the
  OpenCode runtime or its wire DTOs.
- Conversation changes come only from the shared PI-090 tracker and are
  associated with the requested Conversation/run. Do not query Pi session
  diff, parse message text, or create a second tracker/state source.
- Skills come only from packaged managed resources and the target Agent's
  explicit selection. Commands merge Makelore, valid Pi and selected-Skill
  entries with stable DTOs and Makelore-first deduplication.
- The new `/api/coding` route/type/test surface contains no todo, share,
  revert/unrevert, checkpoint or file-rollback shape. Existing
  `/api/opencode` code remains untouched for PI-140 removal.
- Exclude PI-100 project/Agent/Conversation CRUD, prompt, SSE, interactions and
  runtime diagnostics; exclude PI-110/120/130 Renderer state/UI work.
- Do not invent an attachment read endpoint: neither PI-105 nor the normative
  route table assigns its transport.
- Real external Provider verification remains **Explicitly Waived / Accepted
  Risk** with `realTurnVerified=false`; macOS x64/arm64 remains deferred to
  mandatory PI-150. Neither is a Pass.
- Do not create subagents. Keep all writes in this isolated worktree and leave
  canonical project memory to a later integration task.

## Plan

1. Define the smallest vendor-neutral file/change/skill/command contracts and
   lock the supported file UX and path boundaries with focused tests.
2. Implement the Main-owned Project File Service and the PI-105 leaf routes,
   including the minimal planner-approved
   `GET /api/coding/conversations/:id/changes` route.
3. Wire one shared product-services composition into `HostApiContext`, route
   registration and Electron Main without taking PI-100 route ownership.
4. Add focused service/route/facade/dispatcher/Electron seam coverage for path
   rejection, redaction, bounds, tracker identity and managed catalog rules.
5. Run focused tests, typecheck, lint, full unit, Vite build, Windows Electron
   verification and project-document gates; commit and request planner review.

## Outcome

- Added shared vendor-neutral file/change/Skill/command DTOs and a typed
  Renderer facade for the seven PI-105 endpoints.
- Added a Main-owned `CodingProjectFileService` with Git-aware discovery,
  bounded non-Git fallback, bounded UTF-8 previews/search, binary rejection,
  ignore-directory handling, and lexical/realpath containment.
- Added the five normative file/search/Skill routes plus Conversation command
  and planner-approved changes routes. Known input errors are typed and
  unknown filesystem/service failures are redacted.
- Added `CodingProductHost` composition and wired Electron Main to one shared
  attachment store, `PiProductTools`, and its single
  `ConversationChangeTracker`. The current active-project catalog is injected
  as a temporary project-selection adapter until PI-100 replaces composition;
  no OpenCode runtime call or fallback is used by the new service.
- Product command projection is Makelore-first, accepts only safe Pi metadata,
  includes only selected managed Skills, and strips raw Pi/source/provider
  fields. The host has a `get_commands` result injection seam for PI-100's
  runtime composition.
- Added focused unit and Windows Electron coverage for Git/non-Git files,
  Unicode truncation, path rejection/redaction, shared tracker identity,
  catalog filtering, seven route DTOs, Renderer encoding, and Main dispatcher.
- Architecture review reproduced two reachable parity gaps in the first
  implementation commit. The follow-up recognizes porcelain-v2 unmerged
  records as `conflicted` in both file status and target-run changes, and maps
  length-changing Unicode case-fold indices back to the original line before
  returning search submatches. Both failures now have real regression tests.

## Verification

- `corepack pnpm exec vitest run tests/unit/coding-project-files.test.ts tests/unit/coding-product-services.test.ts tests/unit/coding-files-routes.test.ts tests/unit/coding-product-tools-facade.test.ts` — Pass, 4 files / 12 tests after review fixes.
- `corepack pnpm exec vitest run --config vitest.electron.config.ts tests/electron-runtime/coding-files-host.test.ts` — Pass, 1 file / 1 test (focused seam).
- `corepack pnpm run typecheck` — Pass.
- `corepack pnpm run lint:check` — Pass with 6 pre-existing warnings and no errors.
- `corepack pnpm run build:vite` — Pass; existing dynamic-import/chunk-size warnings remain.
- `corepack pnpm test` — Pass after review fixes, 207 files / 2239 passed / 2 skipped. The first pre-review run had one Windows temporary-file `EPERM` and one async AI-hardware loading timeout; both passed when isolated and complete-suite reruns passed.
- `corepack pnpm run test:electron:windows` — Pass, 3 files / 7 tests. A direct Vitest invocation was intentionally discarded because it bypassed the repository's local-Electron wrapper.
- Planner incremental acceptance review through `81c3c5b` — **PASS**;
  Standards 0 findings, Spec 0 findings. The review confirmed porcelain-v2
  conflict projection, original-coordinate Unicode matching, contextual Greek
  case folding, shared composition, the temporary active-project adapter and
  the PI-100 live-`get_commands` seam.
- Real Provider verification — **Explicitly Waived / Accepted Risk**;
  `realTurnVerified=false`, not Pass.
- macOS x64/arm64 — deferred to mandatory PI-150, not Pass.

## Follow-ups

- PI-100 must pass the target Conversation worker's read-only Pi
  `get_commands` projection into `createCodingProductHost.listPiCommands` when
  it composes the production `CodingConversationRuntime`. Until that runtime
  exists in Main, the route deterministically returns Makelore plus selected
  managed-Skill commands.
- PI-100 should replace the injected current active-project catalog adapter
  with its vendor-neutral project service without changing the PI-105 host
  contract or creating another product-tools/change-tracker instance.

## Promotion Candidates

- None recorded.