opencode-ext-connector 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.6.0 - 2026-09-16
+
+- Add the recommended `credentialRole: "owner" | "reader"` option for shared
+  Claude logins: one Linux owner runs the existing Claude CLI authority while
+  readers consume externally managed credentials without refreshing them
+- Keep the existing low-level credential policy options available for advanced
+  control, but reject combining any of them with `credentialRole`
+- Keep omitted credential policy behavior and non-Claude providers unchanged
+
+## 0.5.0 - 2026-09-15
+
+- Add the disabled-by-default Claude CLI credential authority for Linux
+  deployments using `credentialManagement: "external"`
+- Schedule one restricted Claude Code request before credential expiry, with
+  process-shared `flock` coordination, retry handling, and clean shutdown
+- Require util-linux `flock` and Claude Code `2.1.259` or later when enabled;
+  each invocation is a real model request and may consume account usage
+- Keep OAuth, credential persistence, and other providers unchanged; revoked
+  Claude sessions still require interactive `/login`
+
 ## 0.4.0 - 2026-09-11
 
 - Add explicit `ollamaBaseURL` support for trusted remote and self-hosted Ollama

package/README.md

@@ -19,7 +19,7 @@
 
 ## Status
 
-> Independent unofficial community plugin, version **0.4.0**. Package E2E tests exercise the legacy multi-function loader with the OpenCode CLI installed in CI. `@opencode-ai/plugin@1.18.18` is the compile-time plugin API target, not a runtime pin. Source is BSD-3-Clause. This project is not affiliated with, endorsed by, sponsored by, or authorized by OpenCode or any provider. Full terms are in [License and Disclaimer](#license-and-disclaimer).
+> Independent unofficial community plugin, version **0.6.0**. Package E2E tests exercise the legacy multi-function loader with the OpenCode CLI installed in CI. `@opencode-ai/plugin@1.18.18` is the compile-time plugin API target, not a runtime pin. Source is BSD-3-Clause. This project is not affiliated with, endorsed by, sponsored by, or authorized by OpenCode or any provider. Full terms are in [License and Disclaimer](#license-and-disclaimer).
 
 Reuse the Claude, Cursor, Command Code, and Ollama sessions you already have. One `opencode.json` plugin entry publishes live catalogs into OpenCode. Claude and Cursor stay disconnected until OpenCode has a marker or OAuth record and the vendor session is present. Command Code may use an OpenCode-stored direct API key or an existing CLI session/key. Ollama requires the exact session marker plus a responsive trusted daemon.
 
@@ -55,7 +55,7 @@ OpenCode installs configured npm plugins with Bun at startup and caches them. Fo
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-ext-connector@0.4.0"]
+  "plugin": ["opencode-ext-connector@0.6.0"]
 }
 ```
 
@@ -73,15 +73,47 @@ Omitted `providers` enables all four. An explicit list is a strict allow-list. E
 | --- | --- | --- |
 | `providers` | all four | Provider ids to register: `claude`, `cursor`, `command-code`, `ollama`; explicit `[]` disables all |
 | `ollamaBaseURL` | `"http://localhost:11434"` | Absolute `http` or `https` base for the trusted Ollama daemon; path prefixes are preserved |
-| `credentialManagement` | omitted | Preferred authority policy: `"connector"` authorizes refresh and writeback where an adapter supports both; `"external"` prohibits connector refresh and writeback |
+| `credentialRole` | omitted | Recommended shared-login setup: `"owner"` runs the Claude CLI authority on the one credential-owning instance; `"reader"` only reads externally managed credentials |
+| `credentialManagement` | omitted | Advanced policy: `"connector"` authorizes refresh and writeback where an adapter supports both; `"external"` prohibits connector refresh and writeback |
 | `writeBackCredentials` | `false` | **Deprecated:** accepted alone for one migration cycle; controls Claude writeback after refresh |
 | `credentialRefresh.mode` | `"auto"` | **Deprecated:** accepted alone for one migration cycle; controls Claude `"auto"` or `"never"` refresh behavior |
 | `credentialRefresh.leadMs` | `60000` | **Deprecated:** accepted alone for one migration cycle; custom lead times still require this legacy configuration |
+| `credentialAuthority.claudeCli.enabled` | `false` | Claude-only opt-in: see [Opt-in Claude CLI authority timer](#opt-in-claude-cli-authority-timer-claude-only) |
+| `credentialAuthority.claudeCli.leadMs` | `300000` | Claude-only opt-in: milliseconds before credential expiry at which the timer invokes `claude`; non-negative integer |
+| `credentialAuthority.claudeCli.retryMs` | `300000` | Claude-only opt-in: milliseconds to wait before retrying after a non-zero exit, lock conflict, signal, or supervisor failure; positive integer |
 | `catalogReloadMs` | `300000` | Re-run catalog snapshots on this interval; `0` disables |
 | `snapshotTimeoutMs` | `30000` | Per-provider snapshot deadline |
 | `health.initialBackoffMs` | `1000` | Health backoff after a failed snapshot |
 | `health.maximumBackoffMs` | `60000` | Health backoff cap |
 
+### Credential ownership (recommended)
+
+Choose `"owner"` on the one Linux instance that owns and refreshes the shared Claude Code login:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["opencode-ext-connector", { "credentialRole": "owner" }]]
+}
+```
+
+Choose `"reader"` on every instance that only consumes synchronized credentials:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["opencode-ext-connector", { "credentialRole": "reader" }]]
+}
+```
+
+`"owner"` internally selects external credential management and enables the Claude CLI authority with its default timing. `"reader"` selects external credential management without starting the CLI authority. The role describes credential ownership, not whether OpenCode runs on a physical host or in a sandbox guest.
+
+Set exactly one owner per shared Claude login. Owner mode requires Linux, util-linux `flock`, Claude Code `2.1.259` or later on `PATH`, and an authenticated Claude Code session. Each authority invocation is a real model request and may consume account usage. A revoked login still requires interactive `/login`.
+
+Do not combine `credentialRole` with `credentialManagement`, `credentialAuthority`, `credentialRefresh`, or `writeBackCredentials`. Existing low-level configurations remain supported for advanced control.
+
+### Advanced credential policy
+
 `credentialManagement: "connector"` authorizes the connector to refresh and write back credentials where a provider adapter supports both. Today only Claude has that capability, mapping to automatic refresh with a `60_000` ms lead and writeback enabled:
 
 ```jsonc
@@ -114,7 +146,7 @@ Use external authority when another process manages credentials:
 }
 ```
 
-`credentialManagement: "external"` prohibits connector refresh and writeback. Today Claude maps to never-refresh/no-write and can re-read externally managed credentials after a 401. When all credential-policy options are omitted, Claude preserves the legacy defaults: automatic refresh with a `60_000` ms lead and no writeback. If only `credentialManagement` is omitted, supplied deprecated `credentialRefresh` or `writeBackCredentials` options still control behavior. Cursor direct generation and Command Code remain read-only under both modes: on an exact pre-output HTTP 401, they re-read a changed, non-null credential and retry once only. This safe reread is not refresh or writeback, so both modes allow it; Cursor legacy/compatibility generation remains one-shot. Ollama is unaffected. This option does not log in, mint OAuth, synchronize machines, or imply that credentials use file storage.
+`credentialManagement: "external"` prohibits connector refresh and writeback. Today Claude maps to never-refresh/no-write and can re-read externally managed credentials after a 401. To keep that externally managed credential file current from a single Linux host, you can additionally enable the Claude-only [Opt-in Claude CLI authority timer](#opt-in-claude-cli-authority-timer-claude-only); that timer is independent of the connector's own refresh path and off by default. When all credential-policy options are omitted, Claude preserves the legacy defaults: automatic refresh with a `60_000` ms lead and no writeback. If only `credentialManagement` is omitted, supplied deprecated `credentialRefresh` or `writeBackCredentials` options still control behavior. Cursor direct generation and Command Code remain read-only under both modes: on an exact pre-output HTTP 401, they re-read a changed, non-null credential and retry once only. This safe reread is not refresh or writeback, so both modes allow it; Cursor legacy/compatibility generation remains one-shot. Ollama is unaffected. This option does not log in, mint OAuth, synchronize machines, or imply that credentials use file storage.
 
 For one migration cycle, `writeBackCredentials` and `credentialRefresh.*` remain accepted when used without `credentialManagement`; custom `credentialRefresh.leadMs` values still require the legacy configuration. Mixing the new option with either legacy option is rejected with: `` `credentialManagement` cannot be combined with deprecated `credentialRefresh` or `writeBackCredentials` ``.
 
@@ -140,12 +172,45 @@ With all credential-policy options omitted, refreshed Claude tokens stay in memo
 
 Anthropic rotates the refresh token on every refresh and invalidates the previous one. Two copies of `~/.claude/.credentials.json` that both refresh will therefore break each other. Copying the file works only if exactly one machine refreshes and every other machine receives the result before its own copy expires:
 
-- **Refresh authority** (where you log in): `credentialManagement: "connector"`. If you need a custom publication window, use the deprecated legacy options alone for this migration cycle, for example `writeBackCredentials: true` with `credentialRefresh: { mode: "auto", leadMs: 1800000 }`.
-- **External-authority machines**: `credentialManagement: "external"`. They never contact the OAuth endpoint; when a request returns 401 they re-read externally managed credentials and retry once.
+- **Credential owner** (where you log in): use `credentialRole: "owner"` on one Linux instance. For advanced control, use `credentialManagement: "connector"`, or combine `credentialManagement: "external"` with the opt-in [Claude CLI authority timer](#opt-in-claude-cli-authority-timer-claude-only).
+- **Credential readers**: use `credentialRole: "reader"`. They never contact the OAuth endpoint; when a request returns 401 they re-read externally managed credentials and retry once.
 - Synchronize the externally managed credential material from the refresh-authority machine whenever it changes. The option itself does not synchronize machines or require file storage; if you copy `~/.claude/.credentials.json`, OpenCode's own `auth.json` only needs the `anthropic` record once and its other providers should remain untouched.
 
 Machines that refresh on their own — including a Claude Code install that is used interactively — must not share the file. Log in separately there.
 
+### Opt-in Claude CLI authority timer (Claude-only)
+
+This is the advanced form of `credentialRole: "owner"`, useful when custom `leadMs` or `retryMs` values are required. It is disabled by default, does not log in or mint tokens, and requires `credentialManagement: "external"`.
+
+Low-level equivalent:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "opencode-ext-connector",
+      {
+        "credentialManagement": "external",
+        "credentialAuthority": {
+          "claudeCli": {
+            "enabled": true
+          }
+        }
+      }
+    ]
+  ]
+}
+```
+
+After saving the configuration, fully restart OpenCode. The timer requires Linux, util-linux `flock`, Claude Code `2.1.259` or later on `PATH`, an authenticated Claude Code session, and a writable persistent state directory. It is silently disabled on other platforms.
+
+`leadMs` and `retryMs` both default to `300000` (5 minutes). The connector schedules one restricted, single-turn Claude request at the lead boundary. A process-shared non-blocking lock prevents concurrent requests from processes using the same state directory; failures retry after `retryMs` without removing the Claude provider.
+
+Each invocation is a real model request and can count against the account's subscription or billing. Run the timer on exactly one machine per login. It cannot revive a revoked or logged-out session; run interactive `/login` again in that case. Review Anthropic's current [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) before enabling it.
+
+If the timer does not run, check `flock --version`, `claude --version`, the state directory permissions, and both required configuration values. Repeated warnings indicate that the CLI failed, was signalled, or could not be started. To disable the timer, remove `credentialAuthority` or set `enabled` to `false`, then fully restart OpenCode.
+
 ## Host/Guest Sandbox Setup
 
 When OpenCode runs in a container, VM, or another sandbox, treat that runtime as the **guest** and the machine that owns the vendor logins and Ollama daemon as the **host**. The guest has its own `localhost`, home directory, environment, keychains, filesystem permissions, and network namespace. Host sessions are not visible unless you mount their files or inject their environment values explicitly.
@@ -154,7 +219,7 @@ The safest shared-session layout keeps each vendor login owned and refreshed by
 
 | Provider | Host | Guest |
 | --- | --- | --- |
-| Claude | Own and refresh the Claude Code login | Mount the Claude credential directory read-only, set `CLAUDE_CONFIG_DIR` to that guest path, and use `credentialManagement: "external"`; a host macOS Keychain is not available inside a Linux guest; resolve the client version with `ANTHROPIC_CLI_VERSION`, an installed `claude` binary, or npm registry access |
+| Claude | Own and refresh the Claude Code login | Mount the Claude credential directory read-only, set `CLAUDE_CONFIG_DIR` to that guest path, and use `credentialRole: "reader"`; a host macOS Keychain is not available inside a Linux guest; resolve the client version with `ANTHROPIC_CLI_VERSION`, an installed `claude` binary, or npm registry access |
 | Cursor | Own the Cursor CLI login | Mount the credential file at the guest's `${HOME}/.config/cursor/auth.json` read-only, or inject `CURSOR_ACCESS_TOKEN` through the sandbox's secret mechanism; install Node.js 22 or later in the guest |
 | Command Code | Own the CLI login or API key | Mount `${HOME}/.commandcode/auth.json` read-only, or inject `COMMAND_CODE_API_KEY`; resolve the client version with `COMMAND_CODE_CLI_VERSION`, an installed `command-code` binary, or npm registry access |
 | Ollama | Run the trusted daemon and run `ollama signin` there when Cloud access is needed | Copy no Ollama credential; connect only to the daemon selected by `ollamaBaseURL` |
@@ -184,7 +249,7 @@ Use this complete guest `opencode.json` when all four providers are enabled and
       {
         "providers": ["claude", "cursor", "command-code", "ollama"],
         "ollamaBaseURL": "http://host.docker.internal:11434",
-        "credentialManagement": "external",
+        "credentialRole": "reader",
         "catalogReloadMs": 300000,
         "snapshotTimeoutMs": 30000,
         "health": {
@@ -197,7 +262,7 @@ Use this complete guest `opencode.json` when all four providers are enabled and
 }
 ```
 
-`ollamaBaseURL` is a flat connector option in the package tuple, not an OpenCode provider option. The numeric values above are the connector defaults; `credentialManagement: "external"` and the host daemon URL are deliberate overrides for read-only host-owned credentials. Do not put vendor tokens in `opencode.json`; pass them through read-only mounts or the sandbox's secret injection mechanism.
+`ollamaBaseURL` is a flat connector option in the package tuple, not an OpenCode provider option. The numeric values above are the connector defaults; `credentialRole: "reader"` and the host daemon URL are deliberate overrides for read-only host-owned credentials. Do not put vendor tokens in `opencode.json`; pass them through read-only mounts or the sandbox's secret injection mechanism.
 
 For Docker Desktop, `host.docker.internal` normally resolves to the host. A Linux Docker bridge may also need `--add-host=host.docker.internal:host-gateway` or the Compose equivalent:
 
@@ -208,7 +273,7 @@ extra_hosts:
 
 Ollama normally listens on host loopback. For bridge networking, the host may need to start it with `OLLAMA_HOST=0.0.0.0:11434`; restrict the exposed port with host firewall and sandbox network policy. `OLLAMA_HOST` configures the host daemon, while `ollamaBaseURL` configures this connector in the guest. Host networking makes guest `localhost` reach the host but reduces isolation and should be an explicit choice. Other sandbox runtimes need an equivalent host route and must allow outbound access to each enabled provider; allow `registry.npmjs.org` only when Claude or Command Code cannot resolve its client version from an environment value or installed binary.
 
-Alternatively, the guest can own its vendor logins in persistent guest storage. In that mode, run vendor login flows in the guest instead of mounting host credentials. A guest that is the sole Claude refresh owner may use `credentialManagement: "connector"`. Never let the host and guest independently refresh credentials descended from the same Claude refresh token.
+Alternatively, the guest can own its vendor logins in persistent guest storage. In that mode, run vendor login flows in the guest instead of mounting host credentials. A Linux guest that is the sole Claude refresh owner may use `credentialRole: "owner"`; low-level `credentialManagement: "connector"` remains available for connector-managed OAuth refresh and writeback. Never let the host and guest independently refresh credentials descended from the same Claude refresh token.
 
 ## Update and Remove
 
@@ -242,7 +307,7 @@ Ollama `/connect` probes the configured daemon and stores the exact session mark
 
 | Provider | What it does |
 | --- | --- |
-| **Claude** | Reuses existing Claude Code credentials. Does not mint OAuth. Compatibility fetch sends CLI-compatible request metadata and streams Anthropic SSE on the built-in `anthropic` path. `credentialManagement: "connector"` maps to auto-refresh with a `60_000` ms lead and writeback; `"external"` maps to never-refresh/no-write with a credential re-read after 401. Omitting all credential-policy options preserves legacy auto/`60_000` behavior without writeback; if only `credentialManagement` is omitted, supplied deprecated options still control behavior. |
+| **Claude** | Reuses existing Claude Code credentials. Does not mint OAuth. Compatibility fetch sends CLI-compatible request metadata and streams Anthropic SSE on the built-in `anthropic` path. For shared logins, `credentialRole: "owner"` enables the Linux-only Claude CLI authority on one instance, while `"reader"` keeps every other instance read-only with a credential re-read after 401. Low-level `credentialManagement: "connector"` maps to auto-refresh with a `60_000` ms lead and writeback; `"external"` maps to never-refresh/no-write. Omitting all credential-policy options preserves legacy auto/`60_000` behavior without writeback; if only `credentialManagement` is omitted, supplied deprecated options still control behavior. |
 | **Cursor** | Calls Cursor's unpublished client protocol (`api2.cursor.sh` `AgentService`, Connect+protobuf over HTTP/2) with the CLI access token. Credentials remain read-only under both credential-management modes. Direct generation may re-read a changed, non-null credential and retry once only on an exact HTTP 401 before output or effects; this is not refresh or writeback. Legacy/compatibility generation remains one-shot. A plugin-owned Node child communicates over private stdio, keeps tool results on the same bidi Run, never replays parked calls, opens no user-facing daemon, and never spawns `cursor-agent` for generation. Unofficial; not a public Cursor API. After protocol drift there is no implicit fallback — that provider fails. Requires Node.js 22 or later. Live catalog ids are used when present; otherwise the documented fallback is `default`. |
 | **Command Code** | Calls `/alpha/generate` with CLI-compatible request metadata and streams provider-local NDJSON text and tool events. Credentials remain read-only under both credential-management modes. On an exact HTTP 401 before output or effects, it may re-read a changed, non-null credential and retry once only; this is not refresh or writeback. The client version comes from `COMMAND_CODE_CLI_VERSION`, an installed `command-code` binary, or the npm registry. Request metadata includes Node.js version, platform, architecture, and the absolute working directory. Live catalog ids are used when present; otherwise the documented fallback is `Qwen/Qwen3.8-Max`. |
 | **Ollama** | Unaffected by `credentialManagement`. Uses the trusted daemon selected by `ollamaBaseURL` (default `http://localhost:11434`) with `/api/tags`, `/api/pull`, and `/api/chat`; path prefixes are preserved. Publishes models already pulled there, plus exact Cloud tags discovered anonymously from Ollama's official Cloud search and library pages, without connector-supplied credentials. Local entries win exact duplicates. Incomplete Cloud refreshes retain the last complete list. Selecting an absent authorized Cloud tag pulls its lightweight remote reference on first use; concurrent pulls of the same tag and normalized base share one in-flight request, and a failed pull can be retried later. The daemon may then proxy Cloud-tag prompts under the user's Ollama Cloud subscription. The connector never uses an Ollama API key, the usage-billed direct Cloud API, `OLLAMA_HOST`, credentials, custom headers, cookies, or a direct Cloud generation endpoint. |
@@ -258,8 +323,8 @@ The standalone SDK entry is `opencode-ext-connector/ollama`; pass `{ ollamaBaseU
 | `/connect` methods missing | Confirm `plugin` contains `"opencode-ext-connector"` or an exact published `"opencode-ext-connector@<version>"` spec, then fully restart OpenCode. |
 | Provider enabled but no models | Omitted `providers` enables all four; an explicit list is a strict allow-list. Claude and Cursor need a marker or OAuth record plus the vendor session; Command Code may use an OpenCode-stored API key or a CLI session/key; Ollama needs the exact marker plus a responsive configured daemon. Fully restart after `/connect` so instance reconstruction picks up new membership. |
 | Claude works until the next start | Omitting all credential-policy options preserves legacy in-memory refresh without writeback. A rotated refresh token can then fail on the next process start; use `credentialManagement: "connector"` when the connector should refresh and write back. If only `credentialManagement` is omitted, check supplied deprecated refresh/writeback options instead. |
-| Claude reports `invalid_grant` on shared credentials | Another machine with the same login already refreshed and rotated the refresh token. Give one machine refresh authority with `credentialManagement: "connector"` and use `"external"` on the others, or log in separately. |
-| Configuration rejects credential options | Do not combine the new and legacy options; the exact error is: `` `credentialManagement` cannot be combined with deprecated `credentialRefresh` or `writeBackCredentials` ``. Legacy options remain accepted alone for one migration cycle. |
+| Claude reports `invalid_grant` on shared credentials | Another machine with the same login already refreshed and rotated the refresh token. Set `credentialRole: "owner"` on exactly one Linux instance and `"reader"` everywhere else, or use exactly one documented low-level authority path. Every refresher counts, including connector OAuth refresh and the Claude CLI timer. |
+| Configuration rejects credential options | Do not combine `credentialRole` with any low-level credential option. The exact role-conflict error is: `` `credentialRole` cannot be combined with `credentialManagement`, `credentialAuthority`, `credentialRefresh`, or `writeBackCredentials` ``. Low-level options remain accepted alone; `credentialManagement` still cannot be combined with deprecated refresh/writeback options. |
 | `Claude Code client version is unavailable` | No `ANTHROPIC_CLI_VERSION`, no `claude` binary, and `registry.npmjs.org` was unreachable. Set the variable or allow registry access. |
 | Cursor generation fails | Node.js 22 or later is required. Generation uses the unpublished protocol through a private Node child, not `cursor-agent`. Protocol drift fails that provider; there is no implicit fallback. |
 | Command Code generation fails | The client version could not be resolved: set `COMMAND_CODE_CLI_VERSION`, install `command-code`, or allow access to `registry.npmjs.org`. Request metadata includes Node.js version, platform, architecture, and the absolute working directory. |

package/dist/core/options.d.ts

@@ -2,14 +2,31 @@ import { z } from "zod";
 import type { HealthPolicy } from "./health.js";
 export type CredentialRefreshMode = "auto" | "never";
 export type CredentialManagement = "connector" | "external";
+export type CredentialRole = "owner" | "reader";
 export type CredentialRefreshPolicy = {
     readonly mode: CredentialRefreshMode;
     readonly leadMs: number;
 };
+export type ClaudeCliCredentialAuthority = {
+    readonly enabled: boolean;
+    readonly leadMs: number;
+    readonly retryMs: number;
+};
+export type CredentialAuthority = {
+    readonly claudeCli: ClaudeCliCredentialAuthority;
+};
 export type ConnectorOptionsInput = {
     readonly providers?: readonly ("claude" | "cursor" | "command-code" | "ollama")[] | undefined;
     readonly snapshotTimeoutMs?: number | undefined;
+    readonly credentialRole?: CredentialRole | undefined;
     readonly credentialManagement?: CredentialManagement | undefined;
+    readonly credentialAuthority?: {
+        readonly claudeCli: {
+            readonly enabled: boolean;
+            readonly leadMs?: number | undefined;
+            readonly retryMs?: number | undefined;
+        };
+    } | undefined;
     /** @deprecated Use credentialManagement instead. */
     readonly writeBackCredentials?: boolean | undefined;
     /** @deprecated Use credentialManagement instead. */
@@ -28,6 +45,7 @@ export type ConnectorOptions = {
     readonly snapshotTimeoutMs: number;
     readonly writeBackCredentials: boolean;
     readonly credentialRefresh: CredentialRefreshPolicy;
+    readonly credentialAuthority: CredentialAuthority;
     readonly catalogReloadMs: number;
     readonly health: HealthPolicy;
 };

package/dist/core/options.js

@@ -5,14 +5,30 @@ const NonNegativeSafeIntegerSchema = z.number().int().nonnegative().max(MaximumT
 const ProviderSchema = z.enum(["claude", "cursor", "command-code", "ollama"]);
 const CredentialRefreshModeSchema = z.enum(["auto", "never"]);
 const CredentialManagementSchema = z.enum(["connector", "external"]);
+const CredentialRoleSchema = z.enum(["owner", "reader"]);
+const SafeIntegerSchema = z.number().int().safe();
 const DefaultProviders = [
     "claude",
     "cursor",
     "command-code",
     "ollama",
 ];
+const CredentialAuthorityInputSchema = z
+    .object({
+    claudeCli: z
+        .object({
+        enabled: z.boolean(),
+        leadMs: SafeIntegerSchema.nonnegative().optional(),
+        retryMs: SafeIntegerSchema.positive().optional(),
+    })
+        .strict()
+        .readonly(),
+})
+    .strict()
+    .readonly();
 function resolveCredentialOptions(input) {
-    switch (input.credentialManagement) {
+    const credentialManagement = input.credentialRole === undefined ? input.credentialManagement : "external";
+    switch (credentialManagement) {
         case undefined:
             return {
                 credentialRefresh: Object.freeze({
@@ -37,7 +53,9 @@ const ConnectorOptionsInputSchema = z
     .object({
     providers: z.array(ProviderSchema).optional(),
     snapshotTimeoutMs: PositiveSafeIntegerSchema.optional(),
+    credentialRole: CredentialRoleSchema.optional(),
     credentialManagement: CredentialManagementSchema.optional(),
+    credentialAuthority: CredentialAuthorityInputSchema.optional(),
     writeBackCredentials: z.boolean().optional(),
     credentialRefresh: z
         .object({
@@ -57,6 +75,17 @@ const ConnectorOptionsInputSchema = z
 })
     .strict()
     .superRefine((input, context) => {
+    if (input.credentialRole !== undefined &&
+        (input.credentialManagement !== undefined ||
+            input.credentialAuthority !== undefined ||
+            input.credentialRefresh !== undefined ||
+            input.writeBackCredentials !== undefined)) {
+        context.addIssue({
+            code: "custom",
+            path: ["credentialRole"],
+            message: "`credentialRole` cannot be combined with `credentialManagement`, `credentialAuthority`, `credentialRefresh`, or `writeBackCredentials`",
+        });
+    }
     if (input.credentialManagement !== undefined &&
         (input.credentialRefresh !== undefined || input.writeBackCredentials !== undefined)) {
         context.addIssue({
@@ -65,6 +94,23 @@ const ConnectorOptionsInputSchema = z
             message: "`credentialManagement` cannot be combined with deprecated `credentialRefresh` or `writeBackCredentials`",
         });
     }
+    if (input.credentialAuthority?.claudeCli.enabled === true &&
+        (input.credentialManagement !== "external" ||
+            !(input.providers ?? DefaultProviders).includes("claude"))) {
+        context.addIssue({
+            code: "custom",
+            path: ["credentialAuthority", "claudeCli", "enabled"],
+            message: "Claude CLI credential authority requires external credential management and the Claude provider",
+        });
+    }
+    if (input.credentialRole === "owner" &&
+        !(input.providers ?? DefaultProviders).includes("claude")) {
+        context.addIssue({
+            code: "custom",
+            path: ["credentialRole"],
+            message: "Credential owner role requires the Claude provider",
+        });
+    }
     const initialBackoffMs = input.health?.initialBackoffMs ?? 1_000;
     const maximumBackoffMs = input.health?.maximumBackoffMs ?? 60_000;
     if (initialBackoffMs > maximumBackoffMs) {
@@ -77,11 +123,21 @@ export const ConnectorOptionsSchema = ConnectorOptionsInputSchema.transform((inp
         maximumBackoffMs: input.health?.maximumBackoffMs ?? 60_000,
     });
     const credentialOptions = resolveCredentialOptions(input);
+    const credentialAuthority = Object.freeze({
+        claudeCli: Object.freeze({
+            enabled: input.credentialRole === "owner"
+                ? true
+                : (input.credentialAuthority?.claudeCli.enabled ?? false),
+            leadMs: input.credentialAuthority?.claudeCli.leadMs ?? 300_000,
+            retryMs: input.credentialAuthority?.claudeCli.retryMs ?? 300_000,
+        }),
+    });
     return Object.freeze({
         providers: Object.freeze(input.providers ?? DefaultProviders),
         snapshotTimeoutMs: input.snapshotTimeoutMs ?? 30_000,
         writeBackCredentials: credentialOptions.writeBackCredentials,
         credentialRefresh: credentialOptions.credentialRefresh,
+        credentialAuthority,
         catalogReloadMs: input.catalogReloadMs ?? 300_000,
         health,
     });

package/dist/opencode/host-options.d.ts

@@ -1,7 +1,9 @@
 import type { ConnectorOptionsInput } from "../core/options.js";
-type HostConnectorOptionsInput = Omit<ConnectorOptionsInput, "credentialManagement" | "credentialRefresh" | "writeBackCredentials"> & {
+type HostConnectorOptionsInput = Omit<ConnectorOptionsInput, "credentialAuthority" | "credentialManagement" | "credentialRefresh" | "credentialRole" | "writeBackCredentials"> & {
+    readonly credentialAuthority?: unknown;
     readonly credentialManagement?: unknown;
     readonly credentialRefresh?: unknown;
+    readonly credentialRole?: unknown;
     readonly writeBackCredentials?: unknown;
 };
 export declare function pickConnectorOptionsInput(input: unknown): HostConnectorOptionsInput;

package/dist/opencode/host-options.js

@@ -28,8 +28,10 @@ export function pickConnectorOptionsInput(input) {
     if (typeof input !== "object" || input === null) {
         return {};
     }
-    const preservesCredentialPolicy = "credentialManagement" in input &&
-        (input.credentialManagement === "connector" || input.credentialManagement === "external");
+    const preservesCredentialPolicy = ("credentialManagement" in input &&
+        (input.credentialManagement === "connector" || input.credentialManagement === "external")) ||
+        ("credentialRole" in input &&
+            (input.credentialRole === "owner" || input.credentialRole === "reader"));
     const writeBackCredentials = "writeBackCredentials" in input && input.writeBackCredentials !== undefined
         ? preservesCredentialPolicy
             ? input.writeBackCredentials
@@ -51,9 +53,15 @@ export function pickConnectorOptionsInput(input) {
             : undefined,
         snapshotTimeoutMs: "snapshotTimeoutMs" in input ? positiveInteger(input.snapshotTimeoutMs) : undefined,
         ...(writeBackCredentials === undefined ? {} : { writeBackCredentials }),
+        ...(!("credentialRole" in input) || input.credentialRole === undefined
+            ? {}
+            : { credentialRole: input.credentialRole }),
         ...(!("credentialManagement" in input) || input.credentialManagement === undefined
             ? {}
             : { credentialManagement: input.credentialManagement }),
+        ...(!("credentialAuthority" in input) || input.credentialAuthority === undefined
+            ? {}
+            : { credentialAuthority: input.credentialAuthority }),
         ...(credentialRefresh === undefined ? {} : { credentialRefresh }),
         catalogReloadMs: "catalogReloadMs" in input ? nonNegativeInteger(input.catalogReloadMs) : undefined,
         health: "health" in input ? pickHealth(input.health) : undefined,

package/dist/process/production-supervisor.d.ts

@@ -0,0 +1,20 @@
+import type { ProcessCommand, ProcessExit, ProcessSupervisor } from "../core/process.js";
+export type ProcessSpawnOptions = {
+    readonly shell: false;
+    readonly stdio: "ignore";
+    readonly windowsHide: true;
+};
+export interface SpawnedChild {
+    readonly exitCode: number | null;
+    readonly signalCode: string | null;
+    onSpawn(listener: () => void): () => void;
+    onError(listener: (error: Error) => void): () => void;
+    onExit(listener: (exit: ProcessExit) => void): () => void;
+    kill(signal: "SIGTERM" | "SIGKILL"): boolean;
+}
+export type ProcessSpawn = (command: ProcessCommand, options: ProcessSpawnOptions) => SpawnedChild;
+export type ProductionProcessSupervisorOptions = {
+    readonly spawn?: ProcessSpawn;
+    readonly terminationGraceMs?: number;
+};
+export declare function createProductionProcessSupervisor(options?: ProductionProcessSupervisorOptions): ProcessSupervisor;

package/dist/process/production-supervisor.js

@@ -0,0 +1,171 @@
+import { spawn } from "node:child_process";
+import { OperationCancelledError, ProcessSupervisorError, ResourceDisposedError, } from "../core/errors.js";
+import { createAsyncDisposable } from "../core/lifecycle.js";
+const spawnOptions = {
+    shell: false,
+    stdio: "ignore",
+    windowsHide: true,
+};
+function spawnNodeChild(command, options) {
+    const child = spawn(command.executable, [...command.arguments], {
+        cwd: command.cwd ?? undefined,
+        shell: options.shell,
+        stdio: options.stdio,
+        windowsHide: options.windowsHide,
+    });
+    return {
+        get exitCode() {
+            return child.exitCode;
+        },
+        get signalCode() {
+            return child.signalCode;
+        },
+        onSpawn: (listener) => {
+            child.once("spawn", listener);
+            return () => child.removeListener("spawn", listener);
+        },
+        onError: (listener) => {
+            child.once("error", listener);
+            return () => child.removeListener("error", listener);
+        },
+        onExit: (listener) => {
+            const onExit = (code, signal) => {
+                listener(code === null ? { kind: "signal", signal: signal ?? "unknown" } : { kind: "code", code });
+            };
+            child.once("exit", onExit);
+            return () => child.removeListener("exit", onExit);
+        },
+        kill: (signal) => child.kill(signal),
+    };
+}
+function processFailure(operation, cause) {
+    return new ProcessSupervisorError({ operation, retryable: true, cause });
+}
+class ProductionSupervisedProcess {
+    completion;
+    spawned;
+    disposal;
+    constructor(child, terminationGraceMs) {
+        this.spawned = new Promise((resolve, reject) => {
+            const removeSpawn = child.onSpawn(() => {
+                removeError();
+                resolve();
+            });
+            const removeError = child.onError((error) => {
+                removeSpawn();
+                reject(processFailure("spawn", error));
+            });
+        });
+        this.completion = new Promise((resolve, reject) => {
+            const removeExit = child.onExit((exit) => {
+                removeError();
+                resolve(exit);
+            });
+            const removeError = child.onError((error) => {
+                removeExit();
+                reject(processFailure("wait", error));
+            });
+        });
+        this.disposal = createAsyncDisposable(async () => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            child.kill("SIGTERM");
+            let timer;
+            await Promise.race([
+                this.completion,
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, terminationGraceMs);
+                    timer.unref();
+                }),
+            ]);
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (child.exitCode === null && child.signalCode === null) {
+                if (!child.kill("SIGKILL"))
+                    throw processFailure("terminate", null);
+                await this.completion;
+            }
+        });
+    }
+    ready(signal) {
+        return this.raceCancellation(this.spawned, signal, "start-process");
+    }
+    wait(signal) {
+        return this.raceCancellation(this.completion, signal, "wait-process");
+    }
+    terminate() {
+        return this.disposal.dispose();
+    }
+    dispose() {
+        return this.disposal.dispose();
+    }
+    [Symbol.asyncDispose]() {
+        return this.disposal.dispose();
+    }
+    raceCancellation(operation, signal, name) {
+        if (signal.aborted)
+            return Promise.reject(new OperationCancelledError(name));
+        const deferred = Promise.withResolvers();
+        const onAbort = () => deferred.reject(new OperationCancelledError(name));
+        signal.addEventListener("abort", onAbort, { once: true });
+        operation.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            deferred.resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            deferred.reject(error);
+        });
+        return deferred.promise;
+    }
+}
+export function createProductionProcessSupervisor(options = {}) {
+    const spawnProcess = options.spawn ?? spawnNodeChild;
+    const terminationGraceMs = options.terminationGraceMs ?? 1_000;
+    const active = new Set();
+    const disposalController = new AbortController();
+    let disposalStarted = false;
+    const disposal = createAsyncDisposable(async () => {
+        disposalStarted = true;
+        disposalController.abort();
+        await Promise.all([...active].map((process) => process.terminate()));
+    });
+    const start = async (command, signal) => {
+        if (signal.aborted)
+            throw new OperationCancelledError("start-process");
+        if (disposalStarted)
+            throw new ResourceDisposedError("process-supervisor");
+        let child;
+        try {
+            child = spawnProcess(command, spawnOptions);
+        }
+        catch (error) {
+            throw processFailure("spawn", error);
+        }
+        const process = new ProductionSupervisedProcess(child, terminationGraceMs);
+        active.add(process);
+        try {
+            await process.ready(AbortSignal.any([signal, disposalController.signal]));
+            if (disposalStarted) {
+                await process.terminate();
+                throw new ResourceDisposedError("process-supervisor");
+            }
+            return process;
+        }
+        catch (error) {
+            active.delete(process);
+            if (error instanceof OperationCancelledError)
+                await process.terminate();
+            if (disposalStarted)
+                throw new ResourceDisposedError("process-supervisor");
+            throw error;
+        }
+        finally {
+            void process.wait(new AbortController().signal).then(() => active.delete(process), () => active.delete(process));
+        }
+    };
+    return {
+        start,
+        dispose: disposal.dispose,
+        [Symbol.asyncDispose]: disposal[Symbol.asyncDispose],
+    };
+}

package/dist/providers/claude/credential-authority-scheduler.d.ts

@@ -0,0 +1,23 @@
+import type { Clock } from "../../core/clock.js";
+import { type AsyncDisposableHandle } from "../../core/lifecycle.js";
+import type { ConnectorLogger } from "../../core/logger.js";
+import type { ProcessSupervisor } from "../../core/process.js";
+import type { ClaudeCredentials } from "./credentials.js";
+export type ClaudeCredentialReader = (env: Readonly<Record<string, string | undefined>>, signal: AbortSignal) => Promise<ClaudeCredentials | null>;
+export type ClaudeCredentialAuthorityEnvironment = Readonly<Record<string, string | undefined>> & {
+    readonly HOME?: string;
+    readonly XDG_STATE_HOME?: string;
+};
+export type ClaudeCredentialAuthoritySchedulerOptions = {
+    readonly enabled: boolean;
+    readonly platform?: string;
+    readonly clock: Clock;
+    readonly leadMs: number;
+    readonly retryMs: number;
+    readonly env: ClaudeCredentialAuthorityEnvironment;
+    readonly processSupervisor: ProcessSupervisor;
+    readonly logger: ConnectorLogger;
+    readonly readCredentials?: ClaudeCredentialReader;
+    readonly ensureStateDirectory?: (path: string) => Promise<void>;
+};
+export declare function createClaudeCredentialAuthorityScheduler(options: ClaudeCredentialAuthoritySchedulerOptions): AsyncDisposableHandle;

package/dist/providers/claude/credential-authority-scheduler.js

@@ -0,0 +1,181 @@
+import { mkdir } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { InvalidArgumentError, OperationCancelledError, ProcessSupervisorError, } from "../../core/errors.js";
+import { createAsyncDisposable } from "../../core/lifecycle.js";
+import { readClaudeCredentials } from "./auth.js";
+const AUTHORITY_DIRECTORY = "claude-credential-authority";
+const LOCK_FILE = "authority.lock";
+const LOCK_CONFLICT_EXIT_CODE = 75;
+const MAXIMUM_DELAY_MS = 2_147_483_647;
+const AUTHORITY_PROMPT = "Reply OK without using tools.";
+function authorityStateDirectory(env) {
+    const configuredState = env.XDG_STATE_HOME;
+    if (configuredState !== undefined && configuredState.length > 0 && isAbsolute(configuredState)) {
+        return join(configuredState, "opencode-ext-connector", AUTHORITY_DIRECTORY);
+    }
+    const home = env.HOME;
+    if (home === undefined || home.length === 0 || !isAbsolute(home))
+        return null;
+    return join(home, ".local", "state", "opencode-ext-connector", AUTHORITY_DIRECTORY);
+}
+async function createStateDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+}
+function assertNeverProcessExit(exit) {
+    throw new InvalidArgumentError("processExit", exit);
+}
+export function createClaudeCredentialAuthorityScheduler(options) {
+    if (!Number.isSafeInteger(options.leadMs) || options.leadMs < 0) {
+        throw new InvalidArgumentError("leadMs");
+    }
+    if (!Number.isSafeInteger(options.retryMs) || options.retryMs <= 0) {
+        throw new InvalidArgumentError("retryMs");
+    }
+    if (!options.enabled || (options.platform ?? process.platform) !== "linux") {
+        return createAsyncDisposable(() => undefined);
+    }
+    const controller = new AbortController();
+    const readCredentials = options.readCredentials ?? readClaudeCredentials;
+    const ensureStateDirectory = options.ensureStateDirectory ?? createStateDirectory;
+    const stateDirectory = authorityStateDirectory(options.env);
+    let scheduled;
+    let activeProcess;
+    let activeEvaluation;
+    let disposalStarted = false;
+    const arm = (delayMs) => {
+        if (disposalStarted)
+            return;
+        scheduled?.cancel();
+        scheduled = options.clock.schedule(Math.min(MAXIMUM_DELAY_MS, Math.max(0, Math.trunc(delayMs))), () => {
+            scheduled = undefined;
+            startEvaluation(true);
+        });
+    };
+    const runAuthority = async () => {
+        if (stateDirectory === null)
+            return null;
+        await ensureStateDirectory(stateDirectory);
+        const process = await options.processSupervisor.start({
+            executable: "flock",
+            arguments: [
+                "--exclusive",
+                "--nonblock",
+                "--conflict-exit-code",
+                String(LOCK_CONFLICT_EXIT_CODE),
+                "--no-fork",
+                "--",
+                join(stateDirectory, LOCK_FILE),
+                "claude",
+                "--restricted",
+                "-p",
+                AUTHORITY_PROMPT,
+                "--permission-prompts",
+                "none",
+                "--max-turns",
+                "1",
+                "--output-format",
+                "json",
+            ],
+            cwd: stateDirectory,
+        }, controller.signal);
+        activeProcess = process;
+        try {
+            return await process.wait(controller.signal);
+        }
+        finally {
+            activeProcess = undefined;
+            await process.dispose();
+        }
+    };
+    const evaluate = async (canInvoke) => {
+        const credentials = await readCredentials(options.env, controller.signal);
+        if (disposalStarted)
+            return;
+        const expiresAtMs = credentials?.expiresAtMs ?? null;
+        if (expiresAtMs === null) {
+            arm(options.retryMs);
+            return;
+        }
+        const untilLeadMs = expiresAtMs - options.leadMs - options.clock.nowMs();
+        if (untilLeadMs > 0) {
+            arm(untilLeadMs);
+            return;
+        }
+        if (!canInvoke) {
+            arm(options.retryMs);
+            return;
+        }
+        const exit = await runAuthority();
+        if (disposalStarted)
+            return;
+        if (exit === null) {
+            options.logger.log("warn", "claude.credential-authority.state-unavailable", {});
+            arm(options.retryMs);
+            return;
+        }
+        switch (exit.kind) {
+            case "signal":
+                options.logger.log("warn", "claude.credential-authority.signal-exit", {
+                    signal: exit.signal,
+                });
+                arm(options.retryMs);
+                return;
+            case "code":
+                if (exit.code === LOCK_CONFLICT_EXIT_CODE) {
+                    arm(options.retryMs);
+                    return;
+                }
+                if (exit.code !== 0) {
+                    options.logger.log("warn", "claude.credential-authority.nonzero-exit", {
+                        exitCode: exit.code,
+                    });
+                    arm(options.retryMs);
+                    return;
+                }
+                await evaluate(false);
+                return;
+            default:
+                return assertNeverProcessExit(exit);
+        }
+    };
+    const startEvaluation = (canInvoke) => {
+        if (disposalStarted || activeEvaluation !== undefined)
+            return;
+        const operation = evaluate(canInvoke).catch((error) => {
+            if (error instanceof OperationCancelledError && disposalStarted)
+                return;
+            if (error instanceof ProcessSupervisorError) {
+                options.logger.log("warn", "claude.credential-authority.process-failed", {});
+                arm(options.retryMs);
+                return;
+            }
+            if (error instanceof Error) {
+                options.logger.log("warn", "claude.credential-authority.evaluation-failed", {});
+                arm(options.retryMs);
+                return;
+            }
+            throw error;
+        });
+        activeEvaluation = operation;
+        void operation.then(() => {
+            if (activeEvaluation === operation)
+                activeEvaluation = undefined;
+        }, () => {
+            if (activeEvaluation === operation)
+                activeEvaluation = undefined;
+        });
+    };
+    const disposal = createAsyncDisposable(async () => {
+        disposalStarted = true;
+        scheduled?.cancel();
+        scheduled = undefined;
+        controller.abort();
+        await activeProcess?.terminate();
+        await activeEvaluation;
+    });
+    startEvaluation(true);
+    return {
+        dispose: disposal.dispose,
+        [Symbol.asyncDispose]: disposal[Symbol.asyncDispose],
+    };
+}

package/dist/server.js

@@ -10,6 +10,8 @@ import { getProductionOllamaBundle } from "./opencode/ollama-production.js";
 import { createProviderRegistry, selectConfiguredProviders } from "./opencode/providers.js";
 import { disposeV1LanguageRuntime } from "./opencode/v1-language.js";
 import { buildV1AuthHooks, createV1AuthServer, createV1Server } from "./opencode/v1-module.js";
+import { createProductionProcessSupervisor } from "./process/production-supervisor.js";
+import { createClaudeCredentialAuthorityScheduler } from "./providers/claude/credential-authority-scheduler.js";
 import { writeClaudeCredentials } from "./providers/claude/writeback.js";
 import { productionOllamaFetch } from "./providers/ollama/http.js";
 const env = process.env;
@@ -73,14 +75,28 @@ export const connectorServer = async (input, options) => {
         health: connectorOptions.health,
         logger,
     })(input, options);
+    const processSupervisor = createProductionProcessSupervisor();
+    const claudeCliAuthority = connectorOptions.credentialAuthority.claudeCli;
+    const credentialAuthority = createClaudeCredentialAuthorityScheduler({
+        enabled: claudeCliAuthority.enabled,
+        clock,
+        leadMs: claudeCliAuthority.leadMs,
+        retryMs: claudeCliAuthority.retryMs,
+        env,
+        processSupervisor,
+        logger,
+    });
     const dispose = hooks.dispose;
     const disposal = createAsyncDisposable(async () => {
-        try {
-            await dispose?.();
-        }
-        finally {
-            await disposeV1LanguageRuntime();
-        }
+        const results = await Promise.allSettled([
+            Promise.resolve().then(() => credentialAuthority.dispose()),
+            Promise.resolve().then(() => processSupervisor.dispose()),
+            Promise.resolve().then(() => dispose?.()),
+            Promise.resolve().then(disposeV1LanguageRuntime),
+        ]);
+        const primaryFailure = results.find((result) => result.status === "rejected");
+        if (primaryFailure !== undefined)
+            throw primaryFailure.reason;
     });
     return {
         ...hooks,

package/docs/README.ko.md

@@ -19,7 +19,7 @@
 
 ## 상태
 
-> 독립적인 비공식 커뮤니티 플러그인, 버전 **0.4.0**. CI에 설치된 OpenCode CLI를 대상으로 legacy multi-function 로더를 패키지 E2E 테스트로 검증합니다. `@opencode-ai/plugin@1.18.18`은 컴파일 시 사용하는 플러그인 API 대상이며 OpenCode 런타임 버전 고정이 아닙니다. 소스는 BSD-3-Clause입니다. 이 프로젝트는 OpenCode 또는 어떤 프로바이더와도 제휴, 보증, 후원, 승인 관계가 없습니다. 전체 조건은 [라이선스 및 면책 조항](#라이선스-및-면책-조항)에 있습니다.
+> 독립적인 비공식 커뮤니티 플러그인, 버전 **0.6.0**. CI에 설치된 OpenCode CLI를 대상으로 legacy multi-function 로더를 패키지 E2E 테스트로 검증합니다. `@opencode-ai/plugin@1.18.18`은 컴파일 시 사용하는 플러그인 API 대상이며 OpenCode 런타임 버전 고정이 아닙니다. 소스는 BSD-3-Clause입니다. 이 프로젝트는 OpenCode 또는 어떤 프로바이더와도 제휴, 보증, 후원, 승인 관계가 없습니다. 전체 조건은 [라이선스 및 면책 조항](#라이선스-및-면책-조항)에 있습니다.
 
 이미 가지고 있는 Claude, Cursor, Command Code, Ollama 세션을 재사용합니다. `opencode.json` 플러그인 항목 하나가 라이브 카탈로그를 OpenCode에 공개합니다. Claude와 Cursor는 OpenCode에 마커 또는 OAuth 레코드가 있고 벤더 세션이 있을 때까지 연결되지 않은 상태로 유지됩니다. Command Code는 OpenCode에 저장된 직접 API 키 또는 기존 CLI 세션/키를 사용할 수 있습니다. Ollama는 정확한 세션 마커와 응답하는 신뢰된 데몬이 필요합니다.
 
@@ -55,7 +55,7 @@ OpenCode는 시작 시 Bun으로 설정된 npm 플러그인을 설치하고 캐
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-ext-connector@0.4.0"]
+  "plugin": ["opencode-ext-connector@0.6.0"]
 }
 ```
 
@@ -73,15 +73,47 @@ OpenCode는 플러그인 옵션을 두 요소 튜플의 두 번째 항목으로
 | --- | --- | --- |
 | `providers` | 네 프로바이더 모두 | 등록할 프로바이더 id: `claude`, `cursor`, `command-code`, `ollama`; 명시적 `[]`는 모두 비활성화 |
 | `ollamaBaseURL` | `"http://localhost:11434"` | 신뢰하는 Ollama 데몬의 절대 `http` 또는 `https` base; 경로 prefix를 보존 |
-| `credentialManagement` | 생략 | 권장 권한 정책: `"connector"`는 어댑터가 갱신과 writeback을 모두 지원할 때 이를 허용하고, `"external"`은 커넥터의 갱신과 writeback을 금지 |
+| `credentialRole` | 생략 | 권장 공유 로그인 설정: `"owner"`는 자격 증명을 소유한 단일 인스턴스에서 Claude CLI 권한을 실행하고, `"reader"`는 외부 관리 자격 증명만 읽음 |
+| `credentialManagement` | 생략 | 고급 정책: `"connector"`는 어댑터가 갱신과 writeback을 모두 지원할 때 이를 허용하고, `"external"`은 커넥터의 갱신과 writeback을 금지 |
 | `writeBackCredentials` | `false` | **사용 중단 예정:** 한 번의 마이그레이션 주기 동안 단독 사용 시 허용되며, 갱신 후 Claude writeback을 제어 |
 | `credentialRefresh.mode` | `"auto"` | **사용 중단 예정:** 한 번의 마이그레이션 주기 동안 단독 사용 시 허용되며, Claude의 `"auto"` 또는 `"never"` 갱신 동작을 제어 |
 | `credentialRefresh.leadMs` | `60000` | **사용 중단 예정:** 한 번의 마이그레이션 주기 동안 단독 사용 시 허용되며, 사용자 지정 리드 타임에는 여전히 이 레거시 설정이 필요 |
+| `credentialAuthority.claudeCli.enabled` | `false` | Claude 전용 옵트인: [옵트인 Claude CLI 권한 타이머](#옵트인-claude-cli-권한-타이머-claude-전용) 참조 |
+| `credentialAuthority.claudeCli.leadMs` | `300000` | Claude 전용 옵트인: 자격 증명 만료 전 이 밀리초만큼 남았을 때 타이머가 `claude`를 호출; 음수가 아닌 정수 |
+| `credentialAuthority.claudeCli.retryMs` | `300000` | Claude 전용 옵트인: 0이 아닌 종료, 잠금 충돌, 시그널, supervisor 실패 후 재시도까지의 밀리초; 양의 정수 |
 | `catalogReloadMs` | `300000` | 이 간격으로 카탈로그 스냅샷을 다시 실행; `0`이면 비활성화 |
 | `snapshotTimeoutMs` | `30000` | 프로바이더별 스냅샷 기한 |
 | `health.initialBackoffMs` | `1000` | 스냅샷 실패 후 health backoff |
 | `health.maximumBackoffMs` | `60000` | health backoff 상한 |
 
+### 자격 증명 소유권 (권장)
+
+공유 Claude Code 로그인을 소유하고 갱신하는 단일 Linux 인스턴스에서 `"owner"`를 선택하십시오:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["opencode-ext-connector", { "credentialRole": "owner" }]]
+}
+```
+
+동기화된 자격 증명만 소비하는 모든 인스턴스에서는 `"reader"`를 선택하십시오:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [["opencode-ext-connector", { "credentialRole": "reader" }]]
+}
+```
+
+`"owner"`는 내부적으로 external 자격 증명 관리를 선택하고 기본 타이밍으로 Claude CLI 권한을 활성화합니다. `"reader"`는 CLI 권한을 시작하지 않고 external 자격 증명 관리를 선택합니다. 이 역할은 자격 증명 소유권을 뜻하며 OpenCode가 물리 호스트에서 실행되는지, 샌드박스 게스트에서 실행되는지를 뜻하지 않습니다.
+
+공유 Claude 로그인마다 owner를 정확히 하나만 설정하십시오. Owner 모드에는 Linux, util-linux `flock`, `PATH`의 Claude Code `2.1.259` 이상, 인증된 Claude Code 세션이 필요합니다. 각 권한 호출은 실제 모델 요청이며 계정 사용량을 소비할 수 있습니다. 폐기된 로그인은 여전히 대화형 `/login`이 필요합니다.
+
+`credentialRole`을 `credentialManagement`, `credentialAuthority`, `credentialRefresh`, `writeBackCredentials`와 함께 사용하지 마십시오. 기존 저수준 설정은 고급 제어용으로 계속 지원됩니다.
+
+### 고급 자격 증명 정책
+
 `credentialManagement: "connector"`는 프로바이더 어댑터가 갱신과 writeback을 모두 지원하는 경우 커넥터에 그 권한을 부여합니다. 현재 이 기능을 지원하는 것은 Claude뿐이며, 만료 `60_000`ms 전 자동 갱신과 writeback 활성화로 매핑됩니다:
 
 ```jsonc
@@ -114,7 +146,7 @@ OpenCode는 플러그인 옵션을 두 요소 튜플의 두 번째 항목으로
 }
 ```
 
-`credentialManagement: "external"`은 커넥터의 갱신과 writeback을 금지합니다. 현재 Claude에서는 갱신 안 함/writeback 안 함으로 매핑되며, 401 이후 외부에서 관리되는 자격 증명을 다시 읽을 수 있습니다. 모든 자격 증명 정책 옵션을 생략하면 Claude는 레거시 기본 동작을 유지합니다. 즉, `60_000`ms 리드 타임으로 자동 갱신하지만 writeback하지 않습니다. `credentialManagement`만 생략한 경우에는 제공된 사용 중단 예정 `credentialRefresh` 또는 `writeBackCredentials` 옵션이 계속 동작을 제어합니다. 두 모드 모두 Cursor direct 생성과 Command Code는 읽기 전용입니다. 정확한 HTTP 401이 출력이나 효과 전에 발생하면 null이 아니며 변경된 자격 증명을 다시 읽고 한 번만 재시도합니다. 이 안전한 다시 읽기는 갱신이나 writeback이 아니므로 두 모드에서 모두 허용되며, Cursor legacy/compatibility 생성은 한 번만 시도합니다. Ollama에는 영향이 없습니다. 이 옵션은 로그인하거나 OAuth를 발급하지 않고, 머신 간 동기화를 수행하지 않으며, 자격 증명이 파일에 저장된다는 의미도 아닙니다.
+`credentialManagement: "external"`은 커넥터의 갱신과 writeback을 금지합니다. 현재 Claude에서는 갱신 안 함/writeback 안 함으로 매핑되며, 401 이후 외부에서 관리되는 자격 증명을 다시 읽을 수 있습니다. 단일 Linux 호스트에서 외부 관리 자격 증명 파일을 최신 상태로 유지하려면 Claude 전용 [옵트인 Claude CLI 권한 타이머](#옵트인-claude-cli-권한-타이머-claude-전용)를 추가로 활성화할 수 있습니다. 그 타이머는 커넥터 자체의 갱신 경로와 독립적이며 기본값은 꺼짐입니다. 모든 자격 증명 정책 옵션을 생략하면 Claude는 레거시 기본 동작을 유지합니다. 즉, `60_000`ms 리드 타임으로 자동 갱신하지만 writeback하지 않습니다. `credentialManagement`만 생략한 경우에는 제공된 사용 중단 예정 `credentialRefresh` 또는 `writeBackCredentials` 옵션이 계속 동작을 제어합니다. 두 모드 모두 Cursor direct 생성과 Command Code는 읽기 전용입니다. 정확한 HTTP 401이 출력이나 효과 전에 발생하면 null이 아니며 변경된 자격 증명을 다시 읽고 한 번만 재시도합니다. 이 안전한 다시 읽기는 갱신이나 writeback이 아니므로 두 모드에서 모두 허용되며, Cursor legacy/compatibility 생성은 한 번만 시도합니다. Ollama에는 영향이 없습니다. 이 옵션은 로그인하거나 OAuth를 발급하지 않고, 머신 간 동기화를 수행하지 않으며, 자격 증명이 파일에 저장된다는 의미도 아닙니다.
 
 한 번의 마이그레이션 주기 동안 `writeBackCredentials`와 `credentialRefresh.*`는 `credentialManagement` 없이 사용할 때 계속 허용됩니다. 사용자 지정 `credentialRefresh.leadMs` 값에는 여전히 레거시 설정이 필요합니다. 새 옵션을 레거시 옵션 중 하나와 함께 사용하면 다음 정확한 메시지와 함께 거부됩니다: `` `credentialManagement` cannot be combined with deprecated `credentialRefresh` or `writeBackCredentials` ``.
 
@@ -140,12 +172,45 @@ OpenCode는 인스턴스 구성 중에 활성 프로바이더 레지스트리를
 
 Anthropic은 갱신할 때마다 refresh 토큰을 회전시키고 이전 토큰을 무효화합니다. 따라서 `~/.claude/.credentials.json` 사본 두 개가 각자 갱신하면 서로를 깨뜨립니다. 파일 복사는 정확히 한 머신만 갱신하고, 나머지 머신이 자기 사본이 만료되기 전에 그 결과를 받을 때만 동작합니다:
 
-- **갱신 권한 머신** (로그인한 곳): `credentialManagement: "connector"`. 사용자 지정 배포 여유 시간이 필요하면 이번 마이그레이션 주기에는 사용 중단 예정인 레거시 옵션만 사용하십시오. 예: `writeBackCredentials: true`와 `credentialRefresh: { mode: "auto", leadMs: 1800000 }`.
-- **외부 권한 머신**: `credentialManagement: "external"`. OAuth 엔드포인트에 접속하지 않으며, 요청이 401을 반환하면 외부에서 관리되는 자격 증명을 다시 읽고 한 번 재시도합니다.
+- **자격 증명 owner** (로그인한 곳): 단일 Linux 인스턴스에서 `credentialRole: "owner"`를 사용하십시오. 고급 제어가 필요하면 `credentialManagement: "connector"`를 사용하거나 `credentialManagement: "external"`과 옵트인 [Claude CLI 권한 타이머](#옵트인-claude-cli-권한-타이머-claude-전용)를 결합하십시오.
+- **자격 증명 reader**: `credentialRole: "reader"`를 사용하십시오. OAuth 엔드포인트에 접속하지 않으며, 요청이 401을 반환하면 외부에서 관리되는 자격 증명을 다시 읽고 한 번 재시도합니다.
 - 갱신 권한 머신의 외부 관리 자격 증명 자료가 바뀔 때마다 동기화하십시오. 이 옵션 자체는 머신을 동기화하거나 파일 저장을 요구하지 않습니다. `~/.claude/.credentials.json`을 복사하는 경우 OpenCode 자체 `auth.json`에는 `anthropic` 레코드만 한 번 있으면 되며 다른 프로바이더는 건드리지 마십시오.
 
 대화형으로 사용하는 Claude Code 설치처럼 스스로 갱신하는 머신은 파일을 공유하면 안 됩니다. 그곳에서는 별도로 로그인하십시오.
 
+### 옵트인 Claude CLI 권한 타이머 (Claude 전용)
+
+이 옵션은 사용자 지정 `leadMs` 또는 `retryMs`가 필요할 때 쓰는 `credentialRole: "owner"`의 고급 형태입니다. 기본값은 꺼짐이며, 로그인하거나 토큰을 발급하지 않고 `credentialManagement: "external"`이 필요합니다.
+
+저수준 등가 설정:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "opencode-ext-connector",
+      {
+        "credentialManagement": "external",
+        "credentialAuthority": {
+          "claudeCli": {
+            "enabled": true
+          }
+        }
+      }
+    ]
+  ]
+}
+```
+
+설정을 저장한 뒤 OpenCode를 완전히 재시작하십시오. 타이머는 Linux, `PATH`의 util-linux `flock`, Claude Code `2.1.259` 이상, 인증된 Claude Code 세션, writable persistent 상태 디렉터리가 필요합니다. 다른 플랫폼에서는 조용히 비활성화됩니다.
+
+`leadMs`와 `retryMs`의 기본값은 모두 `300000`(5분)입니다. 커넥터는 lead 경계에서 restricted single-turn Claude 요청 하나를 예약합니다. 프로세스 공유 non-blocking lock이 같은 상태 디렉터리를 사용하는 프로세스의 동시 요청을 막고, 실패하면 Claude 프로바이더를 제거하지 않은 채 `retryMs` 후 재시도합니다.
+
+각 호출은 실제 모델 요청이며 계정의 구독 또는 청구 사용량에 포함될 수 있습니다. 로그인 하나당 정확히 한 머신에서만 타이머를 실행하십시오. 폐기되거나 로그아웃된 세션은 복구할 수 없으므로 그 경우 대화형 `/login`을 다시 실행해야 합니다. 활성화 전에 Anthropic의 현재 [Commercial Terms](https://www.anthropic.com/legal/commercial-terms)를 검토하십시오.
+
+타이머가 실행되지 않으면 `flock --version`, `claude --version`, 상태 디렉터리 권한, 두 필수 설정값을 확인하십시오. 반복 경고는 CLI 실행 실패, 시그널 종료, 또는 시작 실패를 뜻합니다. 비활성화하려면 `credentialAuthority`를 제거하거나 `enabled`를 `false`로 설정한 뒤 OpenCode를 완전히 재시작하십시오.
+
 ## 호스트/게스트 샌드박스 설정
 
 OpenCode가 컨테이너, VM 또는 다른 샌드박스에서 실행될 때 그 런타임을 **게스트**, 벤더 로그인과 Ollama 데몬을 소유한 머신을 **호스트**로 봅니다. 게스트에는 자체 `localhost`, 홈 디렉터리, 환경, keychain, 파일 권한, 네트워크 namespace가 있습니다. 파일을 mount하거나 환경 값을 명시적으로 주입하지 않으면 호스트 세션은 게스트에 보이지 않습니다.
@@ -154,7 +219,7 @@ OpenCode가 컨테이너, VM 또는 다른 샌드박스에서 실행될 때 그
 
 | 프로바이더 | 호스트 | 게스트 |
 | --- | --- | --- |
-| Claude | Claude Code 로그인을 소유하고 갱신 | Claude 자격 증명 디렉터리를 read-only로 mount하고 `CLAUDE_CONFIG_DIR`을 그 게스트 경로로 설정하며 `credentialManagement: "external"`을 사용; 호스트 macOS Keychain은 Linux 게스트 안에서 사용할 수 없음; `ANTHROPIC_CLI_VERSION`, 설치된 `claude` 바이너리 또는 npm registry 접근으로 클라이언트 버전 확인 |
+| Claude | Claude Code 로그인을 소유하고 갱신 | Claude 자격 증명 디렉터리를 read-only로 mount하고 `CLAUDE_CONFIG_DIR`을 그 게스트 경로로 설정하며 `credentialRole: "reader"`를 사용; 호스트 macOS Keychain은 Linux 게스트 안에서 사용할 수 없음; `ANTHROPIC_CLI_VERSION`, 설치된 `claude` 바이너리 또는 npm registry 접근으로 클라이언트 버전 확인 |
 | Cursor | Cursor CLI 로그인을 소유 | 자격 증명 파일을 게스트의 `${HOME}/.config/cursor/auth.json`에 read-only로 mount하거나 샌드박스 secret 기능으로 `CURSOR_ACCESS_TOKEN` 주입; 게스트에 Node.js 22 이상 설치 |
 | Command Code | CLI 로그인 또는 API 키를 소유 | `${HOME}/.commandcode/auth.json`을 read-only로 mount하거나 `COMMAND_CODE_API_KEY` 주입; `COMMAND_CODE_CLI_VERSION`, 설치된 `command-code` 바이너리 또는 npm registry 접근으로 클라이언트 버전 확인 |
 | Ollama | 신뢰하는 데몬을 실행하고 Cloud 접근이 필요하면 그곳에서 `ollama signin` 실행 | Ollama 자격 증명을 복사하지 않고 `ollamaBaseURL`로 선택한 데몬에만 연결 |
@@ -184,7 +249,7 @@ COMMAND_CODE_CLI_VERSION=<optional-compatible-version>
       {
         "providers": ["claude", "cursor", "command-code", "ollama"],
         "ollamaBaseURL": "http://host.docker.internal:11434",
-        "credentialManagement": "external",
+        "credentialRole": "reader",
         "catalogReloadMs": 300000,
         "snapshotTimeoutMs": 30000,
         "health": {
@@ -197,7 +262,7 @@ COMMAND_CODE_CLI_VERSION=<optional-compatible-version>
 }
 ```
 
-`ollamaBaseURL`은 OpenCode 프로바이더 옵션이 아니라 패키지 tuple에 넣는 flat 커넥터 옵션입니다. 위 숫자 값은 커넥터 기본값이고, `credentialManagement: "external"`과 호스트 데몬 URL은 read-only 호스트 소유 자격 증명을 위한 의도적인 override입니다. `opencode.json`에 벤더 토큰을 넣지 말고 read-only mount 또는 샌드박스 secret 주입 기능을 사용하십시오.
+`ollamaBaseURL`은 OpenCode 프로바이더 옵션이 아니라 패키지 tuple에 넣는 flat 커넥터 옵션입니다. 위 숫자 값은 커넥터 기본값이고, `credentialRole: "reader"`와 호스트 데몬 URL은 read-only 호스트 소유 자격 증명을 위한 의도적인 override입니다. `opencode.json`에 벤더 토큰을 넣지 말고 read-only mount 또는 샌드박스 secret 주입 기능을 사용하십시오.
 
 Docker Desktop에서는 보통 `host.docker.internal`이 호스트로 resolve됩니다. Linux Docker bridge에는 `--add-host=host.docker.internal:host-gateway` 또는 다음 Compose 설정이 추가로 필요할 수 있습니다:
 
@@ -208,7 +273,7 @@ extra_hosts:
 
 Ollama는 보통 호스트 loopback에서 수신합니다. Bridge networking에서는 호스트가 `OLLAMA_HOST=0.0.0.0:11434`로 시작해야 할 수 있으며, 노출된 port를 호스트 firewall과 샌드박스 network policy로 제한하십시오. `OLLAMA_HOST`는 호스트 데몬을 설정하고 `ollamaBaseURL`은 게스트의 이 커넥터를 설정합니다. Host networking을 사용하면 게스트 `localhost`가 호스트에 도달하지만 격리가 약해지므로 명시적으로 선택해야 합니다. 다른 샌드박스 런타임도 이에 해당하는 호스트 route가 필요하며, 활성화한 각 프로바이더로 outbound 접근을 허용해야 합니다. Claude 또는 Command Code가 환경 값이나 설치된 바이너리에서 클라이언트 버전을 확인할 수 없을 때만 `registry.npmjs.org` 접근을 허용하십시오.
 
-대신 게스트가 persistent guest storage에서 자체 벤더 로그인을 소유할 수도 있습니다. 이 모드에서는 호스트 자격 증명을 mount하지 말고 게스트에서 벤더 로그인 flow를 실행하십시오. 게스트가 유일한 Claude 갱신 소유자라면 `credentialManagement: "connector"`를 사용할 수 있습니다. 호스트와 게스트가 같은 Claude refresh token에서 파생된 자격 증명을 각자 갱신하게 해서는 안 됩니다.
+대신 게스트가 persistent guest storage에서 자체 벤더 로그인을 소유할 수도 있습니다. 이 모드에서는 호스트 자격 증명을 mount하지 말고 게스트에서 벤더 로그인 flow를 실행하십시오. Linux 게스트가 유일한 Claude 갱신 owner라면 `credentialRole: "owner"`를 사용할 수 있으며, 커넥터가 OAuth 갱신과 writeback을 관리해야 할 때는 저수준 `credentialManagement: "connector"`도 계속 사용할 수 있습니다. 호스트와 게스트가 같은 Claude refresh token에서 파생된 자격 증명을 각자 갱신하게 해서는 안 됩니다.
 
 ## 업데이트 및 제거
 
@@ -242,7 +307,7 @@ Ollama `/connect`는 설정된 데몬을 조사하고 정확한 세션 마커를
 
 | 프로바이더 | 하는 일 |
 | --- | --- |
-| **Claude** | 기존 Claude Code 자격 증명을 재사용합니다. OAuth를 발급하지 않습니다. 호환 fetch가 CLI 호환 요청 메타데이터를 보내고, 내장 `anthropic` 경로에서 Anthropic SSE를 스트림합니다. `credentialManagement: "connector"`는 `60_000`ms 리드 타임의 자동 갱신과 writeback으로, `"external"`은 갱신 안 함/writeback 안 함 및 401 이후 자격 증명 다시 읽기로 매핑됩니다. 모든 자격 증명 정책 옵션을 생략하면 레거시 자동 갱신/`60_000` 동작과 writeback 안 함이 유지되며, `credentialManagement`만 생략하면 제공된 사용 중단 예정 옵션이 계속 동작을 제어합니다. |
+| **Claude** | 기존 Claude Code 자격 증명을 재사용합니다. OAuth를 발급하지 않습니다. 호환 fetch가 CLI 호환 요청 메타데이터를 보내고, 내장 `anthropic` 경로에서 Anthropic SSE를 스트림합니다. 공유 로그인에서는 `credentialRole: "owner"`가 단일 인스턴스의 Linux 전용 Claude CLI 권한을 활성화하고, `"reader"`는 나머지 인스턴스를 읽기 전용으로 유지하면서 401 이후 자격 증명을 다시 읽습니다. 저수준 `credentialManagement: "connector"`는 `60_000`ms 리드 타임의 자동 갱신과 writeback으로, `"external"`은 갱신 안 함/writeback 안 함으로 매핑됩니다. 모든 자격 증명 정책 옵션을 생략하면 레거시 자동 갱신/`60_000` 동작과 writeback 안 함이 유지되며, `credentialManagement`만 생략하면 제공된 사용 중단 예정 옵션이 계속 동작을 제어합니다. |
 | **Cursor** | CLI 액세스 토큰으로 Cursor의 미공개 클라이언트 프로토콜(`api2.cursor.sh` `AgentService`, HTTP/2 위의 Connect+protobuf)을 호출합니다. 두 자격 증명 관리 모드 모두 자격 증명은 읽기 전용입니다. direct 생성은 정확한 HTTP 401이 출력이나 효과 전에 발생할 때만 null이 아니며 변경된 자격 증명을 다시 읽고 한 번 재시도할 수 있으며, 이는 갱신이나 writeback이 아닙니다. legacy/compatibility 생성은 한 번만 시도합니다. 플러그인이 소유한 Node 자식 프로세스가 private stdio로 통신하고, 툴 결과를 같은 bidi Run에 유지하며, parked call을 절대 재실행하지 않고, 사용자 대면 데몬을 열지 않으며, 생성에 `cursor-agent`를 절대 spawn하지 않습니다. 비공식이며 공개 Cursor API가 아닙니다. 프로토콜이 어긋난 뒤에는 암시적 fallback이 없습니다 — 해당 프로바이더가 실패합니다. Node.js 22 이상이 필요합니다. 라이브 카탈로그 id가 있으면 그것을 쓰고, 없으면 문서화된 fallback은 `default`입니다. |
 | **Command Code** | CLI 호환 요청 메타데이터와 함께 `/alpha/generate`를 호출하고, 프로바이더 로컬 NDJSON 텍스트와 툴 이벤트를 스트림합니다. 두 자격 증명 관리 모드 모두 자격 증명은 읽기 전용입니다. 정확한 HTTP 401이 출력이나 효과 전에 발생하면 null이 아니며 변경된 자격 증명을 다시 읽고 한 번만 재시도할 수 있으며, 이는 갱신이나 writeback이 아닙니다. 클라이언트 버전은 `COMMAND_CODE_CLI_VERSION`, 설치된 `command-code` 바이너리, 또는 npm registry에서 가져옵니다. 요청 메타데이터에는 Node.js 버전, 플랫폼, 아키텍처, 절대 작업 디렉터리가 포함됩니다. 라이브 카탈로그 id가 있으면 그것을 쓰고, 없으면 문서화된 fallback은 `Qwen/Qwen3.8-Max`입니다. |
 | **Ollama** | `credentialManagement`의 영향을 받지 않습니다. `ollamaBaseURL`로 선택한 신뢰된 데몬(기본값 `http://localhost:11434`)의 `/api/tags`, `/api/pull`, `/api/chat`을 사용하며 경로 prefix를 보존합니다. 이미 pull된 모델과, 커넥터 자격 증명 없이 Ollama 공식 Cloud 검색 및 library 페이지에서 익명으로 발견한 정확한 Cloud 태그를 공개합니다. 정확히 중복되는 항목은 로컬이 이깁니다. 불완전한 Cloud 갱신은 마지막 완전한 목록을 유지합니다. 없는 인가된 Cloud 태그를 선택하면 최초 사용 시 lightweight remote reference를 pull합니다. 같은 정규화 base와 태그의 동시 pull은 하나의 in-flight 요청을 공유하며 실패한 pull은 재시도할 수 있습니다. 데몬은 사용자의 Ollama Cloud 구독으로 Cloud 태그 프롬프트를 proxy할 수 있습니다. 커넥터는 Ollama API 키, 사용량 과금 direct Cloud API, `OLLAMA_HOST`, 자격 증명/custom header, cookie, direct Cloud 생성 endpoint를 사용하지 않습니다. |
@@ -258,8 +323,8 @@ Ollama `/connect`는 설정된 데몬을 조사하고 정확한 세션 마커를
 | `/connect` 메서드가 없음 | `plugin`에 `"opencode-ext-connector"` 또는 정확한 공개 `"opencode-ext-connector@<version>"` spec이 있는지 확인한 뒤 OpenCode를 완전히 재시작하십시오. |
 | 프로바이더가 활성화됐지만 모델이 없음 | `providers`를 생략하면 네 프로바이더가 모두 활성화됩니다. 명시적 목록은 엄격한 allow-list입니다. Claude와 Cursor는 마커 또는 OAuth 레코드와 벤더 세션이 필요하고, Command Code는 OpenCode에 저장된 API 키 또는 CLI 세션/키를 사용할 수 있으며, Ollama는 정확한 마커와 응답하는 설정된 데몬이 필요합니다. `/connect` 후 완전히 재시작해야 인스턴스 재생성이 새 소속을 반영합니다. |
 | Claude가 다음 시작 전까지만 동작함 | 모든 자격 증명 정책 옵션을 생략하면 레거시의 메모리 내 갱신과 writeback 안 함이 유지됩니다. 회전된 refresh 토큰은 다음 프로세스 시작에서 실패할 수 있습니다. 커넥터가 갱신하고 기록해야 한다면 `credentialManagement: "connector"`를 사용하십시오. `credentialManagement`만 생략했다면 제공된 사용 중단 예정 갱신/writeback 옵션을 확인하십시오. |
-| 공유 자격 증명에서 Claude가 `invalid_grant`를 보고함 | 같은 로그인을 쓰는 다른 머신이 이미 갱신해서 refresh 토큰이 회전됐습니다. 한 머신에 `credentialManagement: "connector"`로 갱신 권한을 주고 나머지에는 `"external"`을 사용하거나, 별도로 로그인하십시오. |
-| 설정이 자격 증명 옵션을 거부함 | 새 옵션과 레거시 옵션을 함께 사용하지 마십시오. 정확한 오류는 다음과 같습니다: `` `credentialManagement` cannot be combined with deprecated `credentialRefresh` or `writeBackCredentials` ``. 레거시 옵션은 한 번의 마이그레이션 주기 동안 단독으로 계속 허용됩니다. |
+| 공유 자격 증명에서 Claude가 `invalid_grant`를 보고함 | 같은 로그인을 쓰는 다른 머신이 이미 갱신해서 refresh 토큰이 회전됐습니다. 단일 Linux 인스턴스에 `credentialRole: "owner"`를, 나머지 모든 인스턴스에 `"reader"`를 설정하거나 문서화된 저수준 권한 경로를 정확히 하나만 사용하십시오. 커넥터 OAuth 갱신과 Claude CLI 타이머를 포함해 모든 갱신자가 집계됩니다. |
+| 설정이 자격 증명 옵션을 거부함 | `credentialRole`을 어떤 저수준 자격 증명 옵션과도 함께 사용하지 마십시오. 정확한 역할 충돌 오류는 다음과 같습니다: `` `credentialRole` cannot be combined with `credentialManagement`, `credentialAuthority`, `credentialRefresh`, or `writeBackCredentials` ``. 저수준 옵션은 단독으로 계속 허용되며, `credentialManagement`는 여전히 사용 중단 예정인 갱신/writeback 옵션과 함께 사용할 수 없습니다. |
 | `Claude Code client version is unavailable` | `ANTHROPIC_CLI_VERSION`도, `claude` 바이너리도 없고 `registry.npmjs.org`에 접근할 수 없었습니다. 변수를 설정하거나 registry 접근을 허용하십시오. |
 | Cursor 생성이 실패함 | Node.js 22 이상이 필요합니다. 생성은 `cursor-agent`가 아니라 private Node 자식 프로세스를 통한 미공개 프로토콜을 사용합니다. 프로토콜이 어긋나면 해당 프로바이더가 실패하며, 암시적 fallback은 없습니다. |
 | Command Code 생성이 실패함 | 클라이언트 버전을 확인할 수 없었습니다: `COMMAND_CODE_CLI_VERSION`을 설정하거나, `command-code`를 설치하거나, `registry.npmjs.org` 접근을 허용하십시오. 요청 메타데이터에는 Node.js 버전, 플랫폼, 아키텍처, 절대 작업 디렉터리가 포함됩니다. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-ext-connector",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "External provider connector for OpenCode",
   "type": "module",
   "license": "BSD-3-Clause",