TORCH/docs/ARCHITECTURE_DECISIONS.md

# TORCH architecture decisions

Status date: 2026-09-27

This ledger resolves the implementation decisions identified by
`PORTABLE_AGENT_FLEET_SPEC.md` section 31. A decision marked **accepted** is
the current portable-core contract. A decision marked **gated** identifies a
feature boundary TORCH must not cross until a follow-up decision and acceptance
evidence exist.

## ADR-001: SQLite state and retention

**Status:** accepted.

Machine-local structured state uses one SQLite database per installed project,
with WAL, foreign keys, and a bounded busy timeout. Messages, acknowledgements,
audit records, presence, leases, check receipts, integration requests, context
samples, schedule runs, and Fleet changes share the project identity but remain
separate tables. TORCH performs no automatic history deletion. Retention or
compaction must be an explicit, owner-authorized operation added with recovery
tests; until then, durable records are append-preserving.

## ADR-002: Control-plane transport

**Status:** accepted.

The service layer is an in-process API. The agent-facing transport is MCP over
stdio and the non-MCP fallback is the structured CLI. The Fleet Console exposes
a read-only loopback HTTP observation projection, plus only specifically
approved local owner actions documented in separate decisions. There is no
required daemon, Unix socket, network message queue, or hosted database. A
future socket transport must preserve identity binding and cannot become the
data model.

## ADR-003: Project identity and repository moves

**Status:** accepted for the first release; moves are gated.

Installation creates an opaque project UUID stored in tracked configuration,
the ownership manifest, and machine-local metadata. All three must agree.
Machine-local state also records the canonical absolute repository root, and a
different root fails closed. Moving a managed repository therefore requires a
future explicit migration command that verifies identity and rewrites only the
local root binding; TORCH must not infer a move from a matching directory name.

## ADR-004: Runtime process supervision

**Status:** accepted.

Runtime adapters own process-specific creation, resume, status, capture, and
stop behavior and declare every capability. TORCH persists stable Fleet
identity and runtime session IDs but does not require a resident supervisor.
Unsupported controls fail explicitly and durable messages remain available.
The optional system-schedule launcher uses user systemd on Linux; macOS and
Windows launchers are separate adapters and are not claimed by this release.

## ADR-005: Configuration and generated files

**Status:** accepted.

`.torch/torch.yaml`, approved decisions, and tracked backlog records are
authoritative. `roster.yaml` and prompts are reviewable materializations of an
approved organization. The ownership manifest records their exact hashes;
doctor reports drift, and generated prose never overrides configuration.
Changing organization requires the Fleet-change workflow rather than editing a
generated prompt and treating it as policy.

## ADR-006: Runtime capability negotiation

**Status:** accepted.

Every adapter implements the common operation surface and declares support for
each operation. Startup validates the declaration before planning a launch.
The minimum useful adapter can create or resume a session and exchange durable
messages through CLI/MCP; live steering, hooks, listing, and stopping may be
reported unsupported. TORCH never substitutes an unsupported native feature
silently.

## ADR-007: Check invalidation

**Status:** accepted for the first release.

A check pass is reusable only for the exact Git commit and the exact hash of its
configured definition. A dirty or changing worktree produces no transferable
pass. Additional non-Git inputs require a future declared input-fingerprint
schema; until then projects must encode them in the check definition or rerun
the check. Branch names alone never validate a receipt.

## ADR-008: Local canonical remote naming

**Status:** accepted.

The local bare canonical remote is named `torch-canonical`, never `origin`, and
lives under machine-local project state as `remote.git`. Creation refuses an
existing path, remote-name collision, or dirty checkout. The configured remote
and path are recorded in tracked configuration and the ownership manifest.

## ADR-009: Multi-machine security

**Status:** gated.

The first release is single-machine and exposes no network control-plane write
surface. Multi-machine transport is prohibited until a separate decision
defines mutual authentication, encryption, project isolation, replay defense,
revocation, and recovery, with adversarial acceptance tests. A forge remote is
not a substitute for control-plane authentication.

## ADR-010: Distribution and update signing

**Status:** gated.

Local candidate builds use exact tree hashing, versioned compatibility
metadata, isolated state, and atomic activation/rollback. They are not signed.
Publishing a package or enabling unattended remote updates is blocked until a
follow-up decision selects artifact signing, trusted-key rotation, provenance,
and offline rollback verification. Local `npm pack` qualification does not
claim supply-chain authenticity.

## ADR-011: Project-specific coordination hierarchy

**Status:** gated.

The installed organization config now accepts a versioned role graph, and
TORCH persists sustained-evidence proposals, exposes them for owner review,
and prepares a read-only pilot plan. A separate owner-confirmed CLI activation
now commits the approved graph, derived manager schedules, ownership-manifest
hashes, and pilot record after freshness checks. It does not launch an identity
or modify a system timer. Doctor reports graph roles bound to missing
identities, and the read-only Console renders approved roles, identity status,
reporting links, coordination links, and implementation ownership. Fresh,
resumed, and on-demand identity briefs now include the current role,
responsibility, authority, reporting, direct-report, coordination, and
implementation-ownership context from the active graph, bound into the prompt
digest. A new read-only hierarchy assessment measures recurring cross-domain
backlog, coordination-request, manager-approval, and handoff events in each
project's configured observation window; it recommends review but never creates
or activates a role. Real-fleet measurement, roster binding across every
activation path, pilot outcome measurement, adoption, and reversal remain
incomplete.
Do not represent the full adaptive organization as implemented or encode
COMBATRIG's proposed departments as the default organization.

The target design is an owner-approved, versioned organization graph generated
from each project's repository and specification. It separates
implementation ownership from coordination, fleet operations, program
priority, and independent review authority. The graph permits optional
coordination levels, one primary owner-facing role, and direct peer
communication. Reporting links do not confer worktree access, task
reassignment, or release authority. One shared backlog remains authoritative;
program and domain documents are summaries, not task queues.

A proposed lead must own a concrete integrated outcome. In this design,
headcount alone must never trigger an added management layer. Before this ADR
can be closed, TORCH still needs real fleet-pressure assessment, pilot outcome
measurement, adoption, and reversal. Owner-approved pilot activation is
available through the CLI and the local Console's fresh-plan, same-origin
preview/confirm flow. Active tasks, branches, messages, and implementation
ownership must remain preserved throughout.

## ADR-012: Per-identity runtime and model portability

**Status:** accepted as a product requirement; implementation gated.

TORCH's policy, identity, backlog, and inter-session communication are
provider-independent. Each persistent identity must be assignable an
owner-reviewed runtime profile, including adapter, model identifier, optional
reasoning settings, and launch policy. A single Fleet may mix Claude, Codex,
Pi, other local agent CLIs, and different model tiers at once. Provider/model
labels remain project configuration rather than TORCH-wide assumptions.

An adapter registry must combine built-in and explicitly installed local
plugins. Plugins declare lifecycle capabilities and unsupported settings;
TORCH may not silently substitute a runtime. Durable TORCH messages remain the
inter-session source of truth when a runtime lacks native messaging or live
steering. Runtime-profile changes preserve identity, backlog, worktree, and
resume state, and remain separate from explicit process startup.

The current implementation is partial: install/config, doctor, and lifecycle
startup share a capability-declaring registry; identities can select registered
adapters and model/reasoning profiles; unsupported settings block launch instead
of falling back. Built-in adapters include Claude, Codex, and Pi. The Pi adapter
uses explicit provider/model profiles, Pi's extension API, and an identity-bound
TORCH MCP server started only for individual tool calls; it runs one resumable
turn per process and stores Pi transcripts outside the repository. Pi's local
CLI contract and bridge are covered by regression tests, and installed Pi
0.80.3 passes an offline, no-session extension startup without a provider turn.
Other Pi versions and live provider resume remain qualification gates. Custom
adapter registration still requires an
embedding caller for programmatic use. Profile review and changes are available
through `torch profile show`, `torch profile
set`, and `torch profile defaults`; they validate and write only project-local
config and do not launch runtimes. A user-managed local plugin trust flow now
pins an absolute CommonJS entrypoint to an explicitly reviewed SHA-256 outside
the repository, validates it before registry loading, and lets profile changes
select newly trusted adapters without editing TORCH source. Project config
cannot grant plugin trust, `runtimes list` does not execute plugins, and
revocation does not affect an already-running process. Launch policy uses a
nested `launchPolicy` object in a runtime default (`runtimes.<adapter>`) and/or
identity (`session_manager` or `domains[]`). Identity keys override matching
default keys; omitted keys inherit. Adapters declare exact supported
field/value sets. Unknown fields/values, unsafe modes, and incompatible
combinations block doctor and startup planning before a runtime process is
executed. Custom adapters without `capabilities.launchPolicy.fields` accept no
overrides. `torch profile show`, `profile set`, and `profile defaults` expose
effective policy; edits require `--yes` and change future plans only.

The local Console also supports per-identity changes through a same-origin,
single-use owner preview followed by explicit confirmation. Preview runs the
same CLI validation path as profile edits; confirmation rechecks the exact
configuration digest before writing and records an owner audit event. The UI
shows current versus next-launch state and does not start or alter a running
session. Only built-in and verified, explicitly user-trusted adapters are
offered as available choices.

Codex supports `sandbox=read-only|workspace-write|danger-full-access` and
`approval=on-request|never|approve-for-me`. `approve-for-me` maps only to
`--approve-for-me` and conflicts with an explicit sandbox because the flag
implies workspace-write; other approval modes map to `--ask-for-approval`.
Fresh defaults preserve the previous invocation with `approval=approve-for-me`
and no redundant sandbox field. The historical generated flat pair
`sandbox=workspace-write`, `approval=approve-for-me` is interpreted as that same
effective mode and migrated by the profile CLI before policy edits. Claude
supports only `permissionMode=default|acceptEdits|auto|manual|dontAsk|plan`;
`bypassPermissions` is excluded. Pi exposes no policy overrides and retains
TORCH's fixed `--no-approve`, `--no-extensions`, and `--no-context-files`.

Remaining portability gates: supported-version Pi runtime matrix coverage and
live mixed-provider resume evidence.
Pi extensions execute with Pi's operating-system permissions, so only the
bundled reviewed bridge is loaded for TORCH sessions; project extension
discovery and project trust are disabled for these invocations.

Built-in starting profiles are Codex `gpt-6-luna` with high reasoning effort
and Claude `sonnet`. These are editable defaults, not fixed policy: after
install, change `runtimes.codex.model` / `runtimes.codex.reasoning` or
`runtimes.claude.model` in `.torch/torch.yaml`; set `model` and/or `reasoning`
on `session_manager` or an individual `domains[]` identity to override that
runtime's default. Profile edits do not start, stop, or replace sessions.
Codex receives the selected reasoning effort as an invocation-scoped
`model_reasoning_effort` override, leaving the user's global Codex config
untouched.

Runtime defaults and per-identity overrides are resolved consistently by
startup planning, doctor, the live identity/agent interfaces, and dashboard
snapshots. Agents can query their own effective profile without relying on a
stale prompt copy. Owners can use `torch profile show`, `torch profile set`, and
`torch profile defaults` to review or edit installed project-local profiles.
Each write requires explicit `--yes`, validates the full project config, and
only changes future launch plans; it never starts or reconfigures a running
session.

## ADR-013: Repository analysis snapshot and approval freshness

**Status:** accepted.

Repository analysis operates on the live working tree: tracked files plus
unignored, non-symlink regular files not yet tracked. It reports tracked and
untracked coverage separately and never executes project content. A domain
proposal binds Git history, `HEAD`, external specification hashes, and a
working-tree fingerprint over visible paths plus analysis-relevant source and
manifest contents. Installation recomputes this fingerprint; any relevant
working-tree drift invalidates approval even when the commit has not changed.
Ignored files are excluded, and the fingerprint is provenance only—it is not
an authorization token.

The deterministic baseline assigns a shared path to a domain only when the
repository graph shows that domain importing that shared component. Other
repository-level candidates remain visible for Session Architect and owner
review; they are not blanket-granted as editable shared paths to every domain.

## ADR-014: Local visual evidence and owner feedback

**Status:** accepted.

Visual review evidence is registered only against an existing backlog task owned
by the publishing Fleet identity, with a full local Git commit SHA and the
runtime session ID captured at publication time. TORCH accepts bounded PNG,
JPEG, WebP, and GIF files from that identity's worktree, rejects symbolic-link
paths, and copies image bytes into the project's private external local state.
The catalog stores content hashes and exposes images only through an
integrity-checking local Console route; project repositories do not gain image
blobs or a second artifact ledger.

Owner comments use the durable message stream as their source of truth. A
comment preview identifies the image, task, target identity, commit, and
message effect before an explicit owner confirmation creates the message. The
Console's loopback feedback endpoint requires a same-origin JSON request and a
single-use, five-minute token bound to the exact preview; confirmation
recomputes the plan, while stale, cross-origin, expired, or replayed requests
fail without creating a message. The snapshot API remains GET-only, and the
Console gains no general task, identity, or lifecycle write access. Private
model reasoning is never exposed. Missing or changed image bytes appear
unavailable, not as verified evidence.

## ADR-015: Browser-local saved backlog views

**Status:** accepted.

Named Console views are bounded, schema-versioned browser preferences scoped by
stable project identity. A view stores only a name and filters over fields
already present in the authoritative backlog snapshot. It does not duplicate
tasks, statuses, ownership, or queue ordering, and it never calls a write API.
Storage errors or malformed data fall back to the unfiltered backlog with an
explanatory status. View edits are explicit: owners may save a new view, update
the selected one, or delete it; each action affects only this browser's saved
presentation preferences.

## ADR-016: Backlog-derived feature and milestone progress

**Status:** accepted.

Backlog tasks may carry optional bounded `feature` and `milestone` labels.
The Session Manager may set labels at task creation or update them with a
revision-checked, reasoned classification action; task-local history and the
control-plane audit record preserve the change. Labels never change task state,
owner, dependencies, evidence, or queue order. The Console derives group status
and completion from the same task records and does not create initiative
records, another task ledger, or inferred project taxonomy. Canceled work is
reported but omitted from the completion denominator. Test, integration,
release, deployment, and live-verification gates remain distinct evidence and
cannot be inferred from progress percentages.

## ADR-017: Preview-confirmed owner priority changes

**Status:** accepted.

The loopback Console may expose one bounded owner control: change a task's
priority. Every change requires a same-origin loopback request, an explicit
reason, a revision-bound single-use preview, and separate confirmation. The
service records the owner, reason, prior/new values, timestamp, revision, and
audit event. The action cannot change state, ownership, evidence, dependencies,
integration, or release status. The snapshot endpoint remains GET-only and no
general-purpose Console mutation API is introduced.

## ADR-018: Preview-confirmed owner task proposals

**Status:** accepted.

The loopback Console may let the configured project owner propose one new
backlog task through an exact, same-origin, five-minute preview and a separate
confirmation. Confirmation creates the task as `proposed` and unassigned;
selected domains are routing suggestions only. The Session Manager retains
triage, readiness, dependency, and assignment authority. Creation records an
owner audit event and is idempotent for a repeated confirmation token. It does
not start, stop, or steer any runtime. The task remains in the existing
authoritative backlog and the observation endpoint remains GET-only.

## ADR-019: Serialized canonical integration

**Status:** accepted.

TORCH owns one serialized landing authority per project. Landing acquires a
cross-process project-state write lock before revalidating the request, target
branch, exact check receipts, authorization, and fast-forward eligibility. The
lock remains held through the canonical Git ref update and durable result
record. A competing lander fails closed with a retryable busy result and must
recompute its plan; after target advancement, stale candidates converge and
rerun required checks on the exact resulting commit. Authorized requests are
drainable in durable insertion order through one explicit `torch integrate
drain` invocation. After each landing, later requests are re-evaluated; sibling
tips that omit the new target become `needs_convergence` until their owner
merges the current target and records fresh exact-commit checks. The drain is
one-shot by default, requires explicit confirmation, and is not installed as a
daemon or timer. An owner may separately define an exact-config system schedule
to invoke the same drain no more frequently than once per minute; each ticket
still needs its own landing-authority authorization and fresh exact-commit
receipts. The schedule cannot merge/converge worktrees, push remotes, or start
AI runtimes. Specialists do not push directly to the canonical branch.
External forge credentials can bypass this local queue, so branch
protection/credential isolation remains optional defense in depth rather than a
false claim of local enforcement.

## ADR-020: Current instruction rehydration on every resume

**Status:** accepted.

Every fresh start and resume composes a digest-addressed instruction bundle
from the canonical project checkout. TORCH delivers that current bundle through
the selected adapter's supported resume mechanism and exposes the same text and
digest in the Fleet brief. Current instructions override historical conversation
content, and agents re-read the current brief before each new work item. The
bundle is never sourced from a potentially stale specialist worktree. If an
adapter cannot apply the bundle, TORCH must disclose or block rather than claim
the resumed agent has current instructions.

## ADR-021: Hierarchy-aware manager check-ins

**Status:** accepted; organization-aware inspection, durable queue, typed
system-schedule dispatch, default Session Manager cadence, and an opt-in
adapter-mediated wake with an atomic project-wide daily invocation ceiling are
implemented. Installing a persistent timer and live provider qualification
remain gated.

Periodic check-ins derive each manager's direct reports from the active
organization graph. They inspect durable presence/task state, unacknowledged
coordination messages, and explicit approval waits; uncertain natural-language
summaries are not treated as approval facts. Approval requests persist with a
named requester and approver, task/evidence context, state, revision, and
decision metadata. Named AI approvers receive durable inbox messages and may
decide only their own requests; the configured owner decides through explicit
CLI confirmation. Decisions are audited and returned durably to the requester.
Manager check-ins classify direct-report requests by whether the manager, a
peer AI, or the owner must act; they route but never decide on another
approver's behalf. The check-in creates a durable,
bounded request for the manager to inspect and advance its reports. It never
approves, reassigns, edits backlog state, creates identities, or starts provider
sessions by default. If the manager is offline, the event remains queued. An
optional adapter-mediated wake is disabled by default; owner-reviewed schedule
configuration plus a project-wide budget can enable it with an atomic maximum
invocation count shared across manager schedules per UTC day. TORCH uses the configured identity adapter/profile and skips active
managers. This count ceiling is not equivalent to a USD spend ceiling. No
persistent timer is installed without owner approval. New
deterministic project proposals include one 15-minute system schedule for the
Session Manager. Additional manager identities require their own explicitly
configured check-in schedule; project configuration validation rejects an
explicit hierarchy that leaves a manager identity without one. Automatic
schedule generation follows hierarchy planning and activation; activation
surfaces schedule additions and obsolete candidates but does not install or
reconcile a system timer.

## ADR-022: Explicit fast-forward-only forge publication

**Status:** accepted.

Integration and forge publication are separate operations. Specialists submit
verified commits to TORCH's local FIFO integration queue; the landing authority
updates local canonical main. Publishing that landed canonical commit to an
attached forge requires a separate owner-confirmed `torch forge sync --yes`
after a read-only `torch forge sync plan`. TORCH pushes only the exact current
canonical commit with normal Git fast-forward semantics and records the
owner's action and observed result. It never force-pushes, fetches/merges
implicitly, or publishes from the integration drain or its timer. A remote-ahead
or divergent result blocks and requires explicit owner convergence. The
remote's compare-and-update semantics reject a race that advances its ref
after planning. Local integration remains available during forge outages.

## ADR-023: Organization-aware lifecycle ordering

**Status:** accepted.

Startup is topologically ordered by the active reporting graph after role
relationships are projected onto persistent Fleet identities. Managers start
before direct reports. Wind-down reverses that identity order and routes each
active identity's final status to its direct manager identities, preserving
bottom-up reporting as the fleet grows. An identity-level cycle or missing
manager blocks both plans; an acyclic role graph is not sufficient if multiple
roles collapse into a cyclic identity graph. A partial startup leaves already
started managers available for coordination and reports the exact identities
that did start; TORCH does not silently stop them or continue launching after a
failure. Planning alone never invokes a provider. Legacy
`session_manager.start_last: true` remains accepted in existing configs but is
ignored in favor of the active organization graph.

## Consequences

These decisions keep the first usable release local-first and provider-
independent. They also make current boundaries explicit: repository moves,
multi-machine control, non-Linux persistent launchers, published update
channels, and measurement/adoption of live multi-level organization pilots
remain unavailable or owner-gated rather than silently approximated.