# Worktree / ChatGPT Conversation Ownership — Implementation Plan

Status: ready for implementation  
Date: 2026-08-20  
Authoritative spec: `docs/specs/worktree-conversation-ownership.md`  
Repository: `alexcodeplace/chatgpt-orchestrator`

## Outcome

Implement the missing provenance seam so a managed ChatGPT conversation can be durably joined to its orchestrator worker/execution session and then to a Git worktree/branch/landing receipt. The result must support an Overdeck/AWP consumer answering "which conversation owns this worktree?" without process archaeology or agent-maintained owner files.

## Working rules

1. Preserve the existing logical-worker/executor separation in `SPEC.md`.
2. Conversation identity is accepted only from the managed ChatGPT executor binding; never infer it from title/prompt/processes.
3. Keep Git-specific operations behind an adapter/consumer boundary; the orchestrator core stores normalized ownership/provenance records rather than shelling out to Git.
4. Do not store chat bodies, cookies, auth tokens, or credentials.
5. All state mutations are durable/idempotent and append ordered events.
6. Browser qualification uses isolated buildbox profiles/displays only; never the user's active workstation browser.
7. Land coherent milestones to `main`; no implementation is considered complete while it exists only as dirty WIP.

## Phase 0 — Protocol/spec alignment

### O0.1 Add protocol schemas

Add shared protocol schemas/types for:

- `ConversationIdentity`;
- execution-session provenance;
- `OwnershipRecord` current projection;
- ownership lifecycle events;
- ownership lookup keys;
- landing receipt/provenance;
- stable ownership error codes.

Acceptance:

- invalid conversation UUID/URL mismatch rejected;
- `conversation = null` supported for non-ChatGPT executors;
- title cannot act as identity key;
- schema round-trip tests pass.

### O0.2 Extend worker execution binding

Persist optional conversation identity on the logical worker's executor binding once `conversation.created/bound` is observed.

Acceptance: restart/reload preserves exact managed conversation identity and worker binding.

## Phase 1 — Durable ownership domain/persistence

### O1.1 Ownership state machine

Implement service operations for:

- claim;
- bind conversation;
- bind plan/lane/request metadata;
- heartbeat/touch;
- begin/complete handoff;
- release;
- reclaim after proved-dead session;
- record WIP preservation;
- submit;
- land;
- record worktree removal.

Define guarded transitions for states such as:

```text
provisional -> active -> submitted -> landed -> removed
                    \-> released
                    \-> stale -> reclaimed -> active
```

Do not overload worker lifecycle states with worktree lifecycle semantics.

### O1.2 Persistence/indexes

Add transactional persistence and indexes for:

- ownership ID;
- normalized worktree path;
- repo + branch;
- execution session;
- worker;
- conversation UUID;
- source/landed commit.

All mutations append an ownership event in the same persistence transaction.

Acceptance:

- process restart reconstructs identical current projection;
- history is ordered/monotonic;
- duplicate bind and duplicate landing are idempotent;
- worktree deletion does not erase provenance.

## Phase 2 — MCP/control-plane surface

### O2.1 Ownership write operations

Add the narrow write API defined by the spec. Prefer a small ownership tool group rather than exposing a generic metadata store.

Authorization rule: the server resolves conversation identity from the authenticated worker/executor context. The caller cannot claim an arbitrary conversation UUID.

### O2.2 Read/query operations

Implement:

- current owner by worktree/branch;
- list by repository/state;
- history by worktree/branch/ownership ID;
- provenance by landed commit.

Return structured data suitable for direct CLI/UI rendering.

### O2.3 Events

Expose ownership lifecycle events through existing event-list/wait machinery so the root orchestrator/AWP can react without polling Git.

Acceptance: a synthetic root/worker can claim, handoff and land a worktree using only core/MCP APIs.

## Phase 3 — ChatGPT Web identity capture

### O3.1 Adapter identity extraction

Use the existing managed ChatGPT adapter's URL observation seam to parse/normalize `/c/<uuid>` only after ChatGPT assigns the managed conversation identity.

Tests cover:

- fresh managed chat before UUID exists;
- UUID appears after first submission;
- URL navigation retaining same conversation;
- malformed/non-conversation URL;
- unrelated ChatGPT tab excluded;
- title mutation does not change identity.

### O3.2 Extension reporting

Ensure `conversation.created/bound` reports canonical UUID + URL + observed timestamp to the executor bridge exactly once/idempotently.

Do not transmit arbitrary transcript content.

### O3.3 Worker binding convergence

When a worker already has an ownership record before the ChatGPT UUID is available, append `ownership.conversation_bound` when the executor later learns it.

Acceptance: provisional worktree ownership automatically becomes conversation-resolvable without creating a second ownership record.

## Phase 4 — Execution-session seam

### O4.1 Session identity input

Define the normalized execution-session ID field accepted from local runtime integration. It must be stable for a single execution session and support optional parent/root session IDs.

Do not make ChatGPT conversation UUID the execution-session ID.

### O4.2 Resume/handoff semantics

Implement and test:

- same logical worker, new execution session after restart;
- different worker/session explicitly taking over a released/stale worktree;
- denial while an existing owner is live;
- historical chain retained after handoff.

Acceptance: provenance distinguishes original conversation, resumed session and final landing actor.

## Phase 5 — Git/Overdeck adapter contract

This repository defines/tests the consumer contract. If the Git integration remains in the Overdeck repository, land the consumer there in a separate implementation lane using this contract.

### O5.1 Worktree-local projection

Consumer behavior:

- enable worktree config safely;
- write `overdeck.owner.*`, lane and plan-ref keys with `git config --worktree`;
- never dirty the product worktree;
- rehydrate/repair projection from durable orchestrator ownership;
- reject conflicting live-owner state.

### O5.2 Live lock integration

Upgrade existing worktree lock data to carry:

- ownership ID;
- execution-session ID;
- optional conversation UUID;
- claimed/last-seen timestamps.

Dead-session reclaim must append durable release/reclaim events instead of deleting provenance.

### O5.3 CLI

Consumer should provide:

```text
od-worktree who <slug-or-path>
od-worktree list --owners
```

Required output fields:

- worktree/path;
- branch/HEAD/state;
- lane/plan/request;
- runtime/session;
- ChatGPT conversation title/URL/UUID where available;
- last activity;
- latest WIP preservation ref;
- submitted/landed state.

Unknowns must be explicit.

Acceptance: one command answers the ownership question that currently requires manual archaeology.

## Phase 6 — Landing provenance

### O6.1 Submit receipt

At branch submission, record source worktree, branch, source HEAD, ownership ID and submitting execution session.

### O6.2 Land receipt

At successful landing, record landed branch/head and preserve the source ownership chain.

### O6.3 Cleanup

Worktree/branch cleanup appends lifecycle events but does not delete durable provenance.

Acceptance: query by final `main` commit returns the exact source worker/session and ChatGPT conversation when available.

## Phase 7 — Security/privacy hardening

### O7.1 Authorization tests

Prove:

- worker A cannot bind worker B's conversation;
- an untrusted caller cannot invent conversation UUID ownership;
- paths outside allowed Git roots are rejected by the Git-side adapter;
- ownership writes require authenticated worker/executor/session context.

### O7.2 Data minimization

Automated tests scan serialized ownership records/fixtures and reject fields containing:

- cookies;
- bearer/API tokens;
- site credentials;
- prompt/transcript bodies;
- arbitrary browser storage.

### O7.3 Export/redaction

Provide a redacted diagnostic projection that can omit/full-mask conversation URL/UUID outside the trusted local owner UI.

## Phase 8 — Recovery/chaos qualification

Test kill/restart at these boundaries:

1. worktree created before ownership bind;
2. ownership claim persisted before local Git projection;
3. conversation UUID learned before bind event persisted;
4. session dies with dirty worktree;
5. handoff starts before new lock projection;
6. submit recorded before Git push;
7. landing occurs before receipt persistence;
8. worktree deleted immediately after landing.

Every case must converge without duplicate ownership records or lost provenance.

## Phase 9 — Isolated browser E2E

On `debian1/2/3` isolated display/profile only:

1. root creates a worker;
2. extension creates managed ChatGPT conversation;
3. UUID is observed and persisted;
4. simulated/local execution session claims an isolated fixture worktree;
5. ownership lookup returns the exact ChatGPT conversation;
6. worker/session restarts and explicitly resumes/reclaims;
7. source commit is submitted/landed in a fixture repository;
8. worktree is removed;
9. lookup by landed commit still returns the conversation provenance.

No personal chat content is captured in fixtures/receipts.

## Phase 10 — Documentation and rollout

### O10.1 Operator docs

Document:

- identity hierarchy;
- `ownership.*` APIs;
- what is/is not authoritative;
- handoff/reclaim procedure;
- consumer CLI examples;
- privacy boundary.

### O10.2 Migration

Existing worktrees have no trustworthy historical ChatGPT UUID. Migration rules:

- ingest known live execution-session/worktree ownership where authoritative;
- set conversation identity to unknown unless directly proven;
- do not backfill guessed conversation IDs from titles/processes;
- new worktrees use automatic binding from rollout onward.

### O10.3 Feature rollout

Roll out in order:

1. protocol/persistence read-only capability;
2. managed-conversation binding;
3. ownership writes + queries;
4. Git/Overdeck local projection and locks;
5. landing receipts;
6. UI/CLI surfacing;
7. enforcement of live-owner conflict denial.

## Completion definition

This program is complete when:

- managed ChatGPT conversations are durably linked to logical workers;
- execution sessions can claim/release/handoff worktrees without losing history;
- a worktree lookup identifies its owning ChatGPT conversation when one is known;
- a landed commit can be traced back through source worktree/session/worker/conversation;
- dead-session recovery is explicit and provenance-preserving;
- non-ChatGPT executors remain supported;
- no product repository is dirtied by ownership metadata;
- no credential or transcript content enters ownership storage;
- isolated Firefox/Chromium E2E proves the full lifecycle;
- the Git/Overdeck consumer exposes a one-command human-readable ownership view.