# Code tour

Pi Sych starts in `extensions/workbench/index.ts`. The workbench adds
guidance at the beginning of a supervisor turn, loads project-scoped
configuration, and registers the tools and commands that connect Pi to
the focused runtime modules.

## Dispatch and worker lifecycle

`dispatch_worker` is a request/result protocol rather than a task queue.
A supervisor supplies a bounded task packet: the requested capability
mode, expected result, relevant files, selected skills, model role, and
timeout. The workbench passes that packet to the worker engine, which
resolves the files, requires a bootstrapped worker directory, creates a
temporary result location, and starts a clean Pi worker process. The
worker can submit exactly one immutable validated result: `status`,
`summary`, `files`, and `limitations`. Dispatch accepts it only after a
normal exit and verifies that reported project files still exist.
Cancellation, timeout, spawn failure, a signal exit, and a non-zero exit
take precedence over a result file; none is a successful result.

## Project state and SYNC

`project_status` is the mechanical view of project state. It reads
`SYNC.json`, reports changed or missing tracked files and dependency
impact, and can atomically acknowledge files that a human has reviewed.
A hash change says only that content changed; the tool deliberately does
not decide whether that change is correct or conceptually important.

## Compaction and configuration

The workbench can invoke custom compaction when configuration enables
it. The compaction module builds a bounded snapshot of selected project
state and the conversation, asks the active supervisor model for
structured working memory, filters its file references, and appends a
small number of unreviewed proposals to the inbox. Returning no custom
result leaves Pi's standard compactor in control. Configuration is
resolved through the config-directory module so the workbench, worker
setup, model catalog, and optional local resources agree on where
private settings live.

## Optional integrations

MCPorter is an explicit remote-research adapter. It is only added to a
worker that requested remote research, and its diagnostics describe
configuration without exposing credentials. Plannotator is separate from
the workbench: it is a narrow human-review adapter that brings feedback
from a message or file back into the review flow rather than controlling
plans or project state.

Literature search is a worker tool. The worker extension always
registers it, but the worker engine exposes it only when the selected
skills include exact `research`. A query flows to the resolved local
SQLite FTS5 database and comes back as metadata, snippets, scores, and
source paths. The supported `papers` plus external-content `papers_fts`
schema stores canonical metadata separately and indexes filepath, title,
abstract, tags, and DOI; its full FTS5 contract and database-resolution
order are in
[configuration](configuration.html#local-literature-search). This keeps
local research lookup available to a selected research worker without
making it a supervisor-wide service.

For declarations and source links generated from the current runtime
source, see the [live code reference](code-reference.html).