feat: add journaled Cline CLI integration and catalog sync

devlog/_plan/260912_cline_client/000_plan.md

@@ -0,0 +1,24 @@
+# Cline integration roadmap
+
+Cline users need a reversible connection and routed model list. This unit connects the current Cline CLI storage contract through the existing integration operations and dashboard. Cline stores connection settings and the model catalog separately, so one operation must snapshot and restore both files.
+
+Loop: satisfy-spec, HOTL; trigger: #4214 and delegated lane=cline. Scope: config exporters, integration writer/reader/journal projection, existing CLI/catalog/dashboard registries, translated copy, source fixtures. Non-goals: legacy extension storage migration, Cline process control, user configuration changes during development, merges/releases, new dependencies. All local product suites, builds/typecheck/install are NOT RUN by instruction; regression execution belongs to final-tip GitHub hosted CI. Text checks and independent source audits are allowed. No user token/time/agent caps; existing tool/account scope only.
+
+Outcome: DONE requires source-backed contracts, actual implementation, separate PABCD cycles, independent reviews, final cumulative head CI, PR and durable handoff. Unavailable tools or genuine external blockers are recorded without claiming completion. Main implements; inherited read-only subagents review. Native architect role selection is unavailable; the explicit parent instruction authorizes supported spawn for actual design and reflection reviews. No role installation or settings changes.
+
+Sources: [001_contract.md](001_contract.md). Repository owners: src/clients/config-export.ts, src/integrations/{registry,state,writer,journal,store,config-io}. Existing config builder, exact fragment ownership, atomic file writes and journal are reused. No-op/manual-only configuration cannot meet sync/undo; a separate standalone configuration engine is unnecessary.
+
+| Cycle | Deliverable | Dependency | Design |
+| --- | --- | --- | --- |
+| roadmap | Audited docs only | none | This roadmap and all decade docs |
+| contract | Pure Cline documents, paths, paired journal adapter and regression fixtures | roadmap | 010_contract.md |
+| surfaces | Catalog refresh, CLI help and existing dashboard exposure | contract | 020_surfaces.md |
+| verification | Independent audit, fixes, PR publication and final-tip hosted CI | surfaces | 030_verification.md |
+
+PR decision: one cohesive Cline PR unless the audited paired-file foundation is independently useful and large enough to split. Ordinary manual chain only if split; no native stacks. Intermediate commits may be pushed without waiting on CI. Parent owns merge.
+
+Verification: git diff --check (text only), source review, final-head Cross-platform CI (tests/typecheck/GUI build/lint). Source tests use temporary home/store; no real Cline data. Fixture cases: missing/partial install; malformed, non-regular or foreign edited files; wrong version; foreign provider preserved; owned model removal/port change; second-file failure; bookkeeping failure; interrupted transaction and drift; exact two-file restore including absence. A Cline restart is required after externally written catalogs. Live client process behavior is source-backed, not a claimed local canary.
+
+Public source docs update structure/clients/integrations.md plus CLI/UI owning docs for changed surfaces; public user workflow resides in docs-site. Unreleased security analysis stays under .tmp/cline. Durable handoff: .tmp/cline/handoff.md.
+
+Design reflection: ALIGNED D09/D10. R02 accepted: no unattended Cline refresh; explicit sync only with stopped-client precondition. R03 accepted: journal presence never blesses a mixed pair or inconsistent ownership. Verify both intended bytes and final record before clearing a committed marker.

devlog/_plan/260912_cline_client/001_contract.md

@@ -0,0 +1,14 @@
+# Cline source contract
+
+Upstream revision: cline/cline cfe9cadab99617d5013bf89f07b079d105057791, read 2026-09-12. Scope is the current CLI/shared SDK provider store. Legacy VS Code globalState/secrets storage is not the same contract and is not detected as compatible.
+
+- sdk/packages/shared/src/storage/paths.ts:152-185,424-430 resolves CLINE_PROVIDER_SETTINGS_PATH; otherwise CLINE_DATA_DIR/settings/providers.json; otherwise CLINE_DIR/data/settings/providers.json; otherwise ~/.cline/data/settings/providers.json. Relative overrides are rejected by OpenCodex because its cwd is not Cline's cwd.
+- sdk/packages/core/src/types/provider-settings.ts:33-68 defines version=1, optional lastUsedProvider, modes={}, providers[id]={settings,updatedAt,tokenSource}. settings.provider is the provider ID; protocol openai-responses, client openai, baseUrl, apiKey and model are accepted.
+- sdk/packages/core/src/services/llms/provider-settings.ts:155-199,224-315 maps protocol openai-responses to the OpenAI handler while retaining the custom provider ID and namespaced model.
+- sdk/packages/core/src/services/providers/local-provider-registry.ts:48-121 defines sibling models.json: version=1, providers[id]={provider:{name,baseUrl,protocol,client,defaultModelId},models:{id:{name,contextWindow,modalities,supportsVision}}}.
+- The same file:689-716 caches model-file loading per process. Restart Cline after external updates; do not claim a running picker is live-synchronized.
+
+CLINE-D09 accepted: settings.modelCatalog.url is not an OpenAI /v1/models endpoint. Its loader expects models.dev data, and picker paths do not forward that setting. A single providers.json does not meet full catalog acceptance.
+CLINE-D10 accepted: write providers.json plus sibling models.json as one recoverable journal operation. Each rename is atomic; a filesystem has no atomic rename across both files. Stop Cline before apply/refresh/restore and restart after. Interrupted writes require durable recovery and foreign edits must refuse recovery.
+
+All paths above are pinned under https://github.com/cline/cline/blob/cfe9cadab99617d5013bf89f07b079d105057791/ . No upstream implementation is copied; schema-shaped fixtures use synthetic data. No original carry PR or author credit applies. #3833 is a Command Code reference, not a dependency.

devlog/_plan/260912_cline_client/009_roadmap_result.md

@@ -0,0 +1,5 @@
+# Roadmap cycle result
+
+Docs-only roadmap locked after inherited source/design review and independent A audit. Accepted D09/D10, excluded unattended refresh, strengthened journaled recovery recognition, and added target collision refusal. Existing CLI syntax is --client cline / restore --op; no positional alias is invented.
+
+Source audit confirms two files are needed. No product files changed in this cycle. git diff --check is the permitted document whitespace check; local product tests are NOT RUN. Next cycle executes 010_contract.md; downstream implementation and hosted proof remain open. The one-file modelCatalog URL hypothesis did not survive upstream inspection.

devlog/_plan/260912_cline_client/010_contract.md

@@ -0,0 +1,26 @@
+# Contract and paired-file operations
+
+Depends on roadmap. C4 care for reversible config mutation; no local execution. Use existing journal and ownership, not a second ownership database.
+
+NEW src/clients/config-export/cline.ts: typed pure buildClineClientConfig, summarizeCline and buildClineContribution. Build {settings:{version:1,modes:{},providers:{opencodex:{settings:{provider:'opencodex',protocol:'openai-responses',client:'openai',apiKey:LOOPBACK_API_KEY_PLACEHOLDER,baseUrl},updatedAt:stable schema timestamp,tokenSource:'manual'}}},catalog:{version:1,providers:{opencodex:{provider:{name:'OpenCodex',baseUrl,protocol:'openai-responses',client:'openai'},models}}}}. Namespaced routed IDs are model-map keys. Preserve authoritative context and modality metadata; omit invented costs/output limits. Do not manage lastUsedProvider: users select OpenCodex explicitly (cline --provider opencodex --model provider/model), preserving their default. Empty catalog exports no invented default/model. Managed paths are settings.providers.opencodex and catalog.providers.opencodex; schema envelope defaults are initialized only when absent and retained on disable.
+
+MODIFY src/clients/config-export/contracts.ts: append cline to ExportClientId. Creation: EXPORT_CLIENTS; serialization: builder/JSON download; deserialization: isExportClientId and journal isIntegrationClientId; consumers: integration registries, CLI export, management route and browser lists in 020.
+MODIFY src/clients/config-export.ts: import/register cline builder and append EXPORT_CLIENTS.cline; export path helpers using existing absoluteClientPath. destination is providers.json; filename cline-config-bundle.json; format json; hint explains two document members and restart, no standalone direct-file claim; loopbackOnly true.
+MODIFY src/integrations/registry.ts: append cline paths, detect settings directory, sibling lock .lock. Resolve explicit provider-file override first and derive catalog from dirname; no user discovery scanning.
+
+NEW src/integrations/cline-document.ts: private codec between two raw file strings (snapshot bundle) and logical settings/catalog objects (managed fragments). Reads preserve exact raw bytes and file absence. Parsing invokes existing safe strict JSON parser for each member; reject invalid/non-object schema and unsupported version. Rendering initializes missing version=1/modes={} and serializes both native files, then canonicalizes the raw-string snapshot envelope. Never serialize journal-only metadata into Cline files.
+NEW src/integrations/cline-io.ts: adapt the existing IntegrationIO only for cline and the resolved primary path. Secondary path is dirname(primary)/models.json; no caller-provided arbitrary secondary path. Reject primary path named models.json (case-insensitive), and refuse symlink/non-regular members so two logical members cannot alias one target. Read/stat inspect both members; write uses existing atomic writer for each, compensates on any failure. Snapshot remains the existing journal's one bundle snapshot. Persist a private pending transaction before first rename, including original/result bundle and prior ownership; clear only after journal append. Recover an interrupted operation only on an explicit mutation, only if every current file is exactly original or intended result; if its opId is already journaled, recognize completion only when BOTH intended bytes and final ownership match; otherwise retain unsafe pending state. Foreign edits or invalid pending data refuse and retain recovery evidence. Read-only status never performs recovery. Report partial compensation failure truthfully.
+MODIFY src/integrations/config-io.ts: optional begin/finish transaction hooks on IntegrationIO; existing clients unaffected.
+MODIFY src/integrations/writer.ts: resolve Cline adapter after path resolution, invoke begin hook before commit; use client codec at parse/render boundaries; finish after journal or successful compensation; preserve existing state/refusal logic. Restore reads the same bundle and journal. Coordinated mutation locks encompass recovery and commit.
+MODIFY src/integrations/state.ts: same adapter/codec for classification; pending state unsafe; no mutation on read. Journal API's matchesOperationResult projection reads through the adapter so restore eligibility describes both files.
+MODIFY structure/clients/integrations.md: state two-file ownership and transaction/restart/rollback contract.
+
+NEW tests/clients/cline-client.test.ts: source-shaped generation, env precedence, no secrets, model removal/metadata, initialized install and missing install. NEW tests/clients/cline-writer.test.ts: temporary home and store with real writer, both-file exact restore, absent member restore, invalid JSON/schema, occupied provider refusal/explicit overwrite, foreign edits, second-file and journal failures, crash recovery and foreign-edit refusal. Register both paths in scripts/test-layout/layout.json and tests/fixtures/test-layout-expected.json. Extend existing exact client-list assertions without deleting checks.
+
+Activation evidence is final-tip hosted tests. Locally only diff/text audit; code unverified until hosted result. Pending marker is an early recovery mechanism, not cross-process exclusion against Cline: Cline does not share OpenCodex's lock. User-visible contract requires it stopped; filesystem rename cannot prevent a non-cooperating writer. No claim of simultaneous two-file visibility.
+
+A synthesis: accepted target collision guard and regression; post-journal marker cleanup is best-effort and must not cause compensation. Normal Cline settings saves update updatedAt/model, so declare only settings.providers.opencodex.updatedAt and settings.providers.opencodex.settings.model as refreshable; preserve selected model while still in desired catalog, remove it if no longer routed. All connection/auth metadata remains protected.
+
+Contract P resumes previous D: "Docs-only roadmap complete; next contract cycle" (009). No product source changed since source inspection. Implementation uses existing JSON format plus client-specific parse/render dispatch, avoiding a new public ConfigFormat enum. Export is a human-readable {settings,catalog} document bundle; internal journal envelope stores each raw file string for exact restore. This distinction is explicitly documented and tested. Path helper implementation additionally rejects case-insensitive models.json collision. No product command is executed locally.
+
+Implementation delta: cline builder/paths, private raw pair codec, paired IO and pending journal hooks are implemented; normal model/timestamp writes use the existing narrow refreshable-path mechanism. Existing lifecycle tests now read Cline's logical pair through the production adapter instead of treating its primary file as the whole document. Source checks only so far; hosted suite remains in verification cycle. New tests cover file absence, unsafe version/nonregular member, explicit conflict overwrite, model retirement, foreign edits, write/bookkeeping failure and pending recovery.

devlog/_plan/260912_cline_client/019_contract_result.md

@@ -0,0 +1,5 @@
+# Contract implementation checkpoint
+
+The Cline builder, path resolver, raw-byte pair projection, pending recovery and existing writer/journal integration are implemented. Regression source covers normal lifecycle, native schema refusal, two-file compensation and recoverable interruption. Independent implementation review is in flight and is a required input to the final verification cycle.
+
+Local product tests, typecheck, builds and installation: NOT RUN by explicit user instruction. This checkpoint asserts code/source completion only; runtime correctness remains unverified until final cumulative hosted CI. git diff --check is the permitted text check. Next cycle wires existing CLI/dashboard surfaces and explicit catalog sync. No PR or merge yet.

devlog/_plan/260912_cline_client/020_surfaces.md

@@ -0,0 +1,14 @@
+# Existing CLI, catalog and dashboard surfaces
+
+Depends on contract; re-read source after 010 before B. Extend existing entry maps, no new endpoint/component architecture.
+
+Keep Cline out of unattended catalog-refresh default ids because the client must be stopped. MODIFY explicit sync lists src/cli/dispatch.ts and src/server/management/config-routes.ts: append cline. Keep lazy owned-only refresh and foreign-edit refusal; regression in tests/clients/cline-writer.test.ts verifies unowned untouched, owned refresh changes both files, model removal and endpoint changes.
+MODIFY src/cli/registry.ts export usage/summary: append cline/Cline. Existing integration verbs remain --client cline and restore --op ID; documentation must not invent positional arguments. Update focused CLI export/list expectations and existing sync source fixtures.
+
+MODIFY gui/src/pages/integrations/integration-api.ts client tuple, integration-tabs.ts TABS/FILE_CLIENTS, gui/src/app-routing.ts hash list, overview-clients.ts label map, FileIntegrationPage.tsx semantics/label maps, gui/src/components/apikeys-workspace/client-config-clients.ts CLIENTS/labels/marks, gui/src/components/integration-marks.ts exhaustive map: append cline. Reuse existing page and consequence/rollback dialogs. Reuse the existing gui/public/provider-icons/cline-color.svg already used by provider-icons.ts; no new brand asset.
+MODIFY all gui/src/i18n locale modules: append integrations.tab.cline, integrations.semantics.cline, api.clientConfig.clientCline. Copy states: current Cline CLI provider store; both files; stop before mutations, restart after; Undo restores both originals; default provider remains user-controlled. Parent handoff records these exact shared-file touches.
+MODIFY docs-site/src/content/docs/guides/integrations.md: documented installation contract, env precedence, --client verbs, conflict opt-in, --op restore/drift, two-file export format and running-client limitation. Update structure/runtime.md and structure GUI/CLI ownership docs where applicable with factual links to canonical integration contract.
+
+Verification: existing GUI client-list/route/i18n assertions extended for cline. No local GUI tests/build. Final hosted GUI build/lint/tests; obtain hosted screenshot artifact where available and inspect it. If unavailable report missing visual evidence rather than fabricate screenshot. No real user server configuration is used for capture.
+
+Surfaces P resumes 019: "next cycle wires existing CLI/dashboard surfaces and explicit catalog sync." Source lists still end in omo; append Cline only. Existing cline-color.svg is reused. Public guide path verified as guides/integrations.md. Independent core audit corrections remain mandatory in the final verification cycle; these list/copy changes do not depend on its implementation details.

devlog/_plan/260912_cline_client/029_surfaces_result.md

@@ -0,0 +1,5 @@
+# Surface wiring checkpoint
+
+Cline CLI appears in existing integration, export, route and mark registries. Nine dashboard locales explain the paired-file stop/restart and Undo contract. English and existing translated integration guides identify the current CLI schema. Explicit sync includes previously owned Cline files; unattended catalog refresh excludes Cline.
+
+The existing committed Cline color mark is reused. No layout or new UI component was introduced. Local GUI tests/build/typecheck and product suites are NOT RUN. git diff --check is text-only evidence. Runtime and rendered verification remain on the final cumulative hosted tip; core recovery review corrections remain mandatory in the next cycle. Next direction: inspect the two concrete recovery findings, repair with regression source, then publish and track CI.