# CARBON Feedback Loop

Remote and ReviewLoop are included CARBON plugin features, not additional plugin
subscriptions or required installations. Use `/carbon-feedback` (Codex:
`$carbon-feedback`) for local feedback or the complete hosted review lifecycle.
The bundled `carbon-feedback-loop` MCP server exposes `carbon_remote_*` tools.

## Included capabilities

| Area | Included behavior |
| --- | --- |
| Scoped handoff | URL, artifact upload, approved synthetic app tunnel target, bounded context, explicit audience/expiry disclosure |
| Review workspace | CARBON-branded owner and reviewer pages, findings, questions, evidence, event history, My work |
| People | Reviewer profiles/directory, eligibility/ranking, virtual test teams, confirmed invitations and approval |
| Channels | Concurrent web and provider-native document comments, anchored context-drift checks, replies, channel revocation |
| Agent loop | Durable feedback cursors, accepted/declined findings, fix-ready prompts, owner-approved changes, request retest |
| Operations | Queue/claim, team management, statistics, expiry/revocation, persisted state/uploads, health/readiness endpoints |
| Deployment | One CARBON container for private networks or your own internet-facing host; optional public synthetic playground |

Google Drive channels require a connected provider tool to actually read/write
comments. The plugin returns explicit provider operations; it does not invent
provider access. Tunnels require a separately approved tunnel adapter and
synthetic data; configuring a target does not itself prove a working tunnel.
Optional SMTP, Identity Platform, GCS, Postgres, Cloud Tasks and AI-routing/
automated-analysis adapters retain upstream behavior. They require your own
configuration and consent; mail, AI analysis, routing and public mode are off
by default. No endpoint is silently selected.

## Three distinct operating modes

1. **Local only:** existing `carbon_feedback_context` and protected CARBON
   workspace. No server needed; `.carbon/feedback/requests.json` remains intact.
2. **Private hosted:** deploy this folder yourself; use authenticated reviewers,
   audience constraints and HTTPS on private infrastructure or an authenticated
   internet-facing service. Publicly reachable does NOT mean public feedback.
3. **Public playground:** explicitly set `CARBON_REMOTE_PUBLIC_PLAYGROUND=true`
   on a separate deployment with a separate database and secret set. Only public
   synthetic targets belong here. Task configuration must also select public
   classification/playground, and each creation requires synthetic=true and
   publicSharingConfirmed=true. Do not use this for customer or internal data.

CARBON never defaults to the managed Remote/ReviewLoop cloud. Its task-scoped
state is separate from either standalone plugin under `~/.carbon-feedback-loop`
(0700 directory / 0600 files), overridable with `CARBON_REMOTE_STATE_DIR`.
Host-qualified thread IDs are required; do not use a project directory as a
thread ID. Owner capabilities and credentials are sensitive local state,
not report content. They are permission-protected, not an encrypted vault.

## Private container deployment

Copy this entire `feedback-loop/` directory, including `engine/`, to the host.
Copy `.env.example` to `.env`, replace every example secret, and configure your
HTTPS origin. Use independent random API, queue, manager and signing keys.
Use a long URL-safe Postgres password (it is interpolated into DATABASE_URL).

```sh
docker compose --env-file .env -f compose.yaml config --quiet
docker compose --env-file .env -f compose.yaml up -d --build
```

The published port binds to loopback. Terminate TLS at your own reverse proxy
or identity gateway forwarding to `127.0.0.1:8080`. Never enable dev auth in
production. When trusting identity headers, the edge MUST strip incoming
spoofed values and inject authenticated identity/group values. Alternatively
configure verified tester accounts through your Identity Platform project.
Keep manager/queue/API keys server-side; reviewer links are scoped capabilities.

Postgres and uploads use persistent Docker volumes. Back up and test restoration
of BOTH plus signing/configuration secrets; key rotation invalidates capabilities.
Avoid `docker compose down -v` unless intentionally deleting those records.
Monitor `/healthz` and `/readyz`, configure retention and log redaction, and test
identity, uploads, expiry, revoke and restore before inviting real users.

## Internet-facing / arbitrary cloud deployment

```sh
docker build -t carbon-feedback-loop:local .
```

Publish the image to YOUR registry and run it on your chosen container platform.
Set `PORT`, `DATABASE_URL`, `CARBON_REMOTE_PUBLIC_URL` (HTTPS), the secret variables
and durable upload storage (`CARBON_REMOTE_UPLOAD_DIR`, or `CARBON_REMOTE_GCS_BUCKET`).
Do not rely on container-local files across restarts or replicas. Set your
platform's readiness probe to `/readyz`. GCP-specific reference infrastructure
is included in `engine/infra/`; adapt its legacy REVIEWLOOP_/REMOTE_ variables
to CARBON_REMOTE_ and use this CARBON image/start entrypoint. Do not run upstream
deployment snippets unchanged or assume their identity/cloud services are free.

The same image supports private and public hosts. Public playground is an
additional explicit DATA-VISIBILITY choice, not a requirement for public hosting.
No cloud resources, tunnels, invitations or reviewer requests are created merely
by installing the plugin or building its package.

## Coding-agent lifecycle

1. `carbon_remote_service_info` reports the task's destination without contact.
2. `carbon_remote_configure_thread` saves approved destination, classification,
   audience, context/lifetime ceilings and secret ENVIRONMENT VARIABLE NAMES.
   `settingsConfirmed=true` means actual user approval, not agent inference.
3. `carbon_remote_preview` produces full disclosure; obtain confirmation before
   `carbon_remote_create_review` (`sharingConfirmed=true`).
4. Open the returned owner workspace inside the agent when supported. Share only
   reviewer links with approved people. Never distribute owner/admin links.
5. Poll manually with `carbon_remote_poll_feedback`, or use the host's scheduled
   mechanism only if background polling was requested and enabled. Stop on expiry
   or revocation. Provider channels use preview/create/sync/reply/revoke tools.
6. Review context drift, prepare fixes, ask before editing, verify fixes, then
   request retest only when approved. An invitation is not feedback; a claimed
   fix is not a verified fix. Publish a CARBON snapshot with scoped findings and
   feed explicit human feedback into the next plan/confidence assessment.

## Compatibility and provenance

`engine/` is generated from canonical ReviewLoop, with bounded namespace/UI
branding changes; original wire schemas stay compatible. `UPSTREAM.json` records
every source/bundle hash and version. Rebuild with
`node scripts/sync-feedback-loop.mjs /path/to/canonical/reviewloop` from CARBON.
Do not hand-patch the generated engine. Run the CARBON parity test after syncing.
Legacy `feedback-service/` and its existing local requests remain supported;
they are not silently migrated or pointed at this different API. Choose the
extended CARBON tools for new hosted loops.

Upstream package metadata declares Apache-2.0; the standard license text is
included as `LICENSE-APACHE-2.0.txt`. `UPSTREAM.json` retains provenance. The source
snapshot did not supply an additional copyright/NOTICE file; confirm upstream
notice completeness before public redistribution. Dependency licenses remain
with the dependencies installed from the retained lockfile.