opencode-ext-connector 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 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.5.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.5.0"]
 }
 ```
 
@@ -77,6 +77,9 @@ Omitted `providers` enables all four. An explicit list is a strict allow-list. E
 | `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 |
@@ -114,7 +117,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 +143,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 }`.
+- **Refresh authority** (where you log in): choose exactly one refresh path. Use `credentialManagement: "connector"`, or on Linux use `credentialManagement: "external"` with the opt-in [Claude CLI authority timer](#opt-in-claude-cli-authority-timer-claude-only). The parser rejects enabling the CLI timer in connector mode. If you need a custom publication window for connector mode, 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.
 - 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 Linux-only option lets one host use an existing Claude Code login as the refresh authority for an externally managed credential file. It is disabled by default, does not log in or mint tokens, and requires `credentialManagement: "external"`.
+
+Minimal configuration:
+
+```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.
@@ -242,7 +278,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. `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. On Linux only, `credentialManagement: "external"` plus the opt-in `credentialAuthority.claudeCli.enabled: true` timer (see [Opt-in Claude CLI authority timer](#opt-in-claude-cli-authority-timer-claude-only)) can keep an externally managed credential file current by invoking the local `claude` CLI; the timer is off by default and does not log in or extend the underlying session lifetime. 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,7 +294,7 @@ 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. |
+| Claude reports `invalid_grant` on shared credentials | Another machine with the same login already refreshed and rotated the refresh token. Every refresher counts: `credentialManagement: "connector"` refreshes through the OAuth endpoint, and the opt-in `credentialAuthority.claudeCli.enabled` timer refreshes through the local `claude` CLI. Pick exactly one authority: either connector mode, or external mode with the CLI timer on one Linux machine. Keep every other machine on `"external"` with the timer disabled, 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 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. |

package/dist/core/options.d.ts

@@ -6,10 +6,25 @@ 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 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 +43,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,12 +5,26 @@ 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 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) {
         case undefined:
@@ -38,6 +52,7 @@ const ConnectorOptionsInputSchema = z
     providers: z.array(ProviderSchema).optional(),
     snapshotTimeoutMs: PositiveSafeIntegerSchema.optional(),
     credentialManagement: CredentialManagementSchema.optional(),
+    credentialAuthority: CredentialAuthorityInputSchema.optional(),
     writeBackCredentials: z.boolean().optional(),
     credentialRefresh: z
         .object({
@@ -65,6 +80,15 @@ 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",
+        });
+    }
     const initialBackoffMs = input.health?.initialBackoffMs ?? 1_000;
     const maximumBackoffMs = input.health?.maximumBackoffMs ?? 60_000;
     if (initialBackoffMs > maximumBackoffMs) {
@@ -77,11 +101,19 @@ 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.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,5 +1,6 @@
 import type { ConnectorOptionsInput } from "../core/options.js";
-type HostConnectorOptionsInput = Omit<ConnectorOptionsInput, "credentialManagement" | "credentialRefresh" | "writeBackCredentials"> & {
+type HostConnectorOptionsInput = Omit<ConnectorOptionsInput, "credentialAuthority" | "credentialManagement" | "credentialRefresh" | "writeBackCredentials"> & {
+    readonly credentialAuthority?: unknown;
     readonly credentialManagement?: unknown;
     readonly credentialRefresh?: unknown;
     readonly writeBackCredentials?: unknown;

package/dist/opencode/host-options.js

@@ -54,6 +54,9 @@ export function pickConnectorOptionsInput(input) {
         ...(!("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.5.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.5.0"]
 }
 ```
 
@@ -77,6 +77,9 @@ OpenCode는 플러그인 옵션을 두 요소 튜플의 두 번째 항목으로
 | `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 |
@@ -114,7 +117,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 +143,45 @@ OpenCode는 인스턴스 구성 중에 활성 프로바이더 레지스트리를
 
 Anthropic은 갱신할 때마다 refresh 토큰을 회전시키고 이전 토큰을 무효화합니다. 따라서 `~/.claude/.credentials.json` 사본 두 개가 각자 갱신하면 서로를 깨뜨립니다. 파일 복사는 정확히 한 머신만 갱신하고, 나머지 머신이 자기 사본이 만료되기 전에 그 결과를 받을 때만 동작합니다:
 
-- **갱신 권한 머신** (로그인한 곳): `credentialManagement: "connector"`. 사용자 지정 배포 여유 시간이 필요하면 이번 마이그레이션 주기에는 사용 중단 예정인 레거시 옵션만 사용하십시오. 예: `writeBackCredentials: true`와 `credentialRefresh: { mode: "auto", leadMs: 1800000 }`.
+- **갱신 권한 머신** (로그인한 곳): 정확히 하나의 갱신 경로를 선택하십시오. `credentialManagement: "connector"`를 사용하거나, Linux에서는 `credentialManagement: "external"`과 옵트인 [Claude CLI 권한 타이머](#옵트인-claude-cli-권한-타이머-claude-전용)를 함께 사용하십시오. 파서는 connector 모드에서 CLI 타이머 활성화를 거부합니다. connector 모드에 사용자 지정 배포 여유 시간이 필요하면 이번 마이그레이션 주기에는 사용 중단 예정인 레거시 옵션만 사용하십시오. 예: `writeBackCredentials: true`와 `credentialRefresh: { mode: "auto", leadMs: 1800000 }`.
 - **외부 권한 머신**: `credentialManagement: "external"`. OAuth 엔드포인트에 접속하지 않으며, 요청이 401을 반환하면 외부에서 관리되는 자격 증명을 다시 읽고 한 번 재시도합니다.
 - 갱신 권한 머신의 외부 관리 자격 증명 자료가 바뀔 때마다 동기화하십시오. 이 옵션 자체는 머신을 동기화하거나 파일 저장을 요구하지 않습니다. `~/.claude/.credentials.json`을 복사하는 경우 OpenCode 자체 `auth.json`에는 `anthropic` 레코드만 한 번 있으면 되며 다른 프로바이더는 건드리지 마십시오.
 
 대화형으로 사용하는 Claude Code 설치처럼 스스로 갱신하는 머신은 파일을 공유하면 안 됩니다. 그곳에서는 별도로 로그인하십시오.
 
+### 옵트인 Claude CLI 권한 타이머 (Claude 전용)
+
+이 Linux 전용 옵션은 단일 호스트의 기존 Claude Code 로그인을 외부 관리 자격 증명 파일의 갱신 권한으로 사용합니다. 기본값은 꺼짐이며, 로그인하거나 토큰을 발급하지 않고 `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하거나 환경 값을 명시적으로 주입하지 않으면 호스트 세션은 게스트에 보이지 않습니다.
@@ -242,7 +278,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를 스트림합니다. `credentialManagement: "connector"`는 `60_000`ms 리드 타임의 자동 갱신과 writeback으로, `"external"`은 갱신 안 함/writeback 안 함 및 401 이후 자격 증명 다시 읽기로 매핑됩니다. Linux에서만 `credentialManagement: "external"`에 옵트인 `credentialAuthority.claudeCli.enabled: true` 타이머([옵트인 Claude CLI 권한 타이머](#옵트인-claude-cli-권한-타이머-claude-전용) 참조)를 더해 로컬 `claude` CLI를 호출함으로써 외부 관리 자격 증명 파일을 최신 상태로 유지할 수 있습니다. 이 타이머는 기본값이 꺼져 있으며 로그인하지도 기반 세션 수명을 연장하지도 않습니다. 모든 자격 증명 정책 옵션을 생략하면 레거시 자동 갱신/`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,7 +294,7 @@ 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"`을 사용하거나, 별도로 로그인하십시오. |
+| 공유 자격 증명에서 Claude가 `invalid_grant`를 보고함 | 같은 로그인을 쓰는 다른 머신이 이미 갱신해서 refresh 토큰이 회전됐습니다. 모든 갱신자가 집계됩니다. `credentialManagement: "connector"`는 OAuth 엔드포인트를 통해 갱신하고, 옵트인 `credentialAuthority.claudeCli.enabled` 타이머는 로컬 `claude` CLI를 통해 갱신합니다. connector 모드 또는 단일 Linux 머신의 external 모드와 CLI 타이머 중 정확히 하나만 권한으로 선택하십시오. 나머지 모든 머신은 타이머가 비활성화된 `"external"`로 유지하거나 각 머신에서 별도로 로그인하십시오. |
 | 설정이 자격 증명 옵션을 거부함 | 새 옵션과 레거시 옵션을 함께 사용하지 마십시오. 정확한 오류는 다음과 같습니다: `` `credentialManagement` cannot be combined with deprecated `credentialRefresh` or `writeBackCredentials` ``. 레거시 옵션은 한 번의 마이그레이션 주기 동안 단독으로 계속 허용됩니다. |
 | `Claude Code client version is unavailable` | `ANTHROPIC_CLI_VERSION`도, `claude` 바이너리도 없고 `registry.npmjs.org`에 접근할 수 없었습니다. 변수를 설정하거나 registry 접근을 허용하십시오. |
 | Cursor 생성이 실패함 | Node.js 22 이상이 필요합니다. 생성은 `cursor-agent`가 아니라 private Node 자식 프로세스를 통한 미공개 프로토콜을 사용합니다. 프로토콜이 어긋나면 해당 프로바이더가 실패하며, 암시적 fallback은 없습니다. |

package/package.json

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