agentlinkops 0.6.8 → 0.6.10

package/cli/client.js

@@ -1,44 +1,110 @@
 import {restResponseContract} from '../shared/response-contract.js';
+import {CloudError} from './cloud-error.js';
+import {createMcpClient} from './mcp-client.js';
+export {CloudError} from './cloud-error.js';
 // A small HTTP client for the cloud. Scoped keys only; no human session ever reaches here.
 // DP-0036-T13: the CLI names itself so the usage counters can tell it from other REST callers.
 // The version follows the plugin manifests; bump it with them.
-export const CLI_VERSION = '0.6.8';
+export const CLI_VERSION = '0.6.10';
 export const CLI_USER_AGENT = `agentlinkops-cli/${CLI_VERSION}`;
-export class CloudError extends Error {
-  constructor(code, status, details = null) {
-    super(`${code}${status ? ` (${status})` : ''}`);
-    this.name = 'CloudError'; this.code = code; this.status = status; this.details = details;
-    this.exitCode = 2;
-  }
-}
-
-export function createClient({ origin, token, workspaceId, projectId, fetchImpl = globalThis.fetch } = {}) {
+const MAX_ATTEMPTS = 3;
+const MAX_RETRY_WAIT_MS = 5_000;
+const retryableStatus = new Set([429, 503]);
+const sleepDefault = ms => new Promise(resolve => setTimeout(resolve, ms));
+const retryAfterMs = (value, now) => {
+  if (value == null || value === '') return null;
+  if (/^\d+$/u.test(value.trim())) return Number(value.trim()) * 1000;
+  const at = Date.parse(value);
+  return Number.isFinite(at) ? Math.max(0, at - now) : null;
+};
+const backoffMs = attempt => Math.min(MAX_RETRY_WAIT_MS, 250 * 2 ** (attempt - 1));
+const isTimeout = error => ['TimeoutError', 'AbortError'].includes(error?.name) || error?.code === 'ETIMEDOUT';
+export function createClient({ origin, token, workspaceId, projectId, fetchImpl = globalThis.fetch,
+  sleepImpl = sleepDefault, now = () => Date.now(), auth, credentialStore, createSdkClient, resolveHost } = {}) {
   if (!origin) throw new CloudError('NO_CLOUD_ORIGIN', 0);
+  if (auth !== undefined && auth?.kind !== 'oauth') throw new CloudError('OAUTH_CONFIG_INVALID', 400);
+  if (auth?.kind === 'oauth') {
+    if (token) throw new CloudError('OAUTH_CREDENTIAL_CONFLICT', 400);
+    return createMcpClient({origin, workspaceId, projectId, fetchImpl, sleepImpl, now, auth, credentialStore, createSdkClient, resolveHost});
+  }
   if (!token) throw new CloudError('NO_TOKEN', 0);
   const base = origin.replace(/\/$/u, '');
   async function call(method, path, { body = null, query = null } = {}) {
     const url = new URL(base + path);
     for (const [key, value] of Object.entries(query ?? {})) if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
-    const response = await fetchImpl(url.href, {
-      method, redirect: 'error', signal: AbortSignal.timeout(30000),
-      headers: {
-        Authorization: `Bearer ${token}`,
-        'User-Agent': CLI_USER_AGENT,
-        ...(workspaceId ? { 'X-Workspace-ID': workspaceId } : {}),
-        ...(body ? { 'Content-Type': 'application/json' } : {}),
-      },
-      ...(body ? { body: JSON.stringify(body) } : {}),
-    });
-    const text = await response.text();
+    const safeRead = method.toUpperCase() === 'GET';
+    let response, text, retryAfter = null, requestId = null;
+    for (let attempt = 1; attempt <= (safeRead ? MAX_ATTEMPTS : 1); attempt++) {
+      response = undefined; text = undefined; retryAfter = null; requestId = null;
+      try {
+        response = await fetchImpl(url.href, {
+          method, redirect: 'error', signal: AbortSignal.timeout(30000),
+          headers: {
+            Authorization: `Bearer ${token}`,
+            'User-Agent': CLI_USER_AGENT,
+            ...(workspaceId ? { 'X-Workspace-ID': workspaceId } : {}),
+            ...(body ? { 'Content-Type': 'application/json' } : {}),
+          },
+          ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        retryAfter = response.headers.get('Retry-After');
+        requestId = response.headers.get('X-Request-ID') ?? requestId;
+        text = await response.text();
+      } catch (error) {
+        if (safeRead && attempt < MAX_ATTEMPTS) {
+          if (response && retryableStatus.has(response.status)) {
+            const serverDelay = retryAfterMs(retryAfter, now());
+            const delay = serverDelay === null ? backoffMs(attempt)
+              : serverDelay <= MAX_RETRY_WAIT_MS ? serverDelay : null;
+            if (delay !== null) {
+              await sleepImpl(delay);
+              continue;
+            }
+            throw new CloudError(`HTTP_${response.status}`, response.status, null,
+              'The server returned a temporary response and requested a longer wait. Retry after the stated interval.',
+              null, { retryAfter, requestId });
+          }
+          await sleepImpl(backoffMs(attempt));
+          continue;
+        }
+        if (response && !response.ok) {
+          throw new CloudError(`HTTP_${response.status}`, response.status, null,
+            'The server response could not be read completely. Check the request result before trying again.',
+            null, { retryAfter, requestId });
+        }
+        const timedOut = isTimeout(error);
+        const code = timedOut ? 'CLOUD_TIMEOUT' : 'CLOUD_NETWORK_ERROR';
+        const message = timedOut
+          ? safeRead ? `The cloud read timed out after ${attempt} attempt${attempt === 1 ? '' : 's'}. Check the connection before trying again.` : 'The cloud request timed out. Check the operation result before sending it again.'
+          : safeRead ? `The cloud connection failed after ${attempt} read attempt${attempt === 1 ? '' : 's'}. Check the connection before trying again.` : 'The cloud connection failed before the request returned a response. Check the operation result before sending it again.';
+        throw new CloudError(code, 0, { attempts: attempt }, message, null, { requestId, retryAfter });
+      }
+
+      if (safeRead && retryableStatus.has(response.status) && attempt < MAX_ATTEMPTS) {
+        const serverDelay = retryAfterMs(retryAfter, now());
+        const delay = serverDelay === null ? backoffMs(attempt)
+          : serverDelay <= MAX_RETRY_WAIT_MS ? serverDelay : null;
+        // A Retry-After longer than our bounded wait is never shortened into an early retry.
+        if (delay !== null) {
+          await sleepImpl(delay);
+          continue;
+        }
+      }
+      break;
+    }
     let payload = null;
     try { payload = text ? JSON.parse(text) : null; } catch { payload = null; }
     if (!response.ok) {
       // The error BODY is the useful part — a 410 carries the resync instructions, and losing
       // them would turn a recoverable expiry into "the sync failed, try again forever".
-      throw new CloudError(payload?.error?.code ?? `HTTP_${response.status}`, response.status, payload?.error?.details ?? null);
+      const code = payload?.error?.code ?? `HTTP_${response.status}`;
+      const id = payload?.error?.requestId ?? requestId;
+      const envelope = payload?.error ? { ...payload.error } : null;
+      throw new CloudError(code, response.status, payload?.error?.details ?? null,
+        payload?.error?.message ?? null, envelope, { retryAfter, requestId: id });
     }
     const parsed=restResponseContract(path,method).safeParse(payload);
-    if(!parsed.success)throw new CloudError('INVALID_RESPONSE',502);
+    if(!parsed.success)throw new CloudError('INVALID_RESPONSE',502,null,null,null,{requestId});
     return parsed.data;
   }
   return {

package/cli/cloud-error.js

@@ -0,0 +1,21 @@
+export class CloudError extends Error {
+  constructor(code, status, details = null, serverMessage = null, envelope = null, metadata = {}) {
+    super(`${code}${status ? ` (${status})` : ''}`);
+    this.name = 'CloudError'; this.code = code; this.status = status; this.details = details;
+    // DP-0063-T03: the server's message says what to fix; keep it for the CLI to print.
+    this.serverMessage = typeof serverMessage === 'string' ? serverMessage : null;
+    // Keep the public server envelope structured; the CLI must not stringify issues into a message.
+    this.retryAfter = metadata.retryAfter ?? null;
+    this.requestId = metadata.requestId ?? envelope?.requestId ?? null;
+    this.publicError = envelope ? { ...envelope,
+      ...(this.requestId && !envelope.requestId ? { requestId: this.requestId } : {}),
+      ...(this.retryAfter !== null ? { retryAfter: this.retryAfter } : {}),
+    } : this.requestId || this.retryAfter !== null || this.serverMessage ? {
+      code, ...(this.serverMessage ? { message: this.serverMessage } : {}),
+      ...(this.details ? { details: this.details } : {}),
+      ...(this.requestId ? { requestId: this.requestId } : {}),
+      ...(this.retryAfter !== null ? { retryAfter: this.retryAfter } : {}),
+    } : null;
+    this.exitCode = 2;
+  }
+}

package/cli/commands.js

@@ -7,17 +7,20 @@ import { parseArgs } from './args.js';
 import { NUDGE } from './skill.js';
 import { CATALOG_COMMANDS, CATALOG_TOOLSETS } from './catalog.js';
 import { oneLiner } from '../src/tool-views.js';
+import { resolveSchemaPath, listAvailablePaths } from '../shared/exec-grammar.js';
 
 // DP-0036-T05: the CLI's three-level discovery over the cloud catalog — index (`tools`),
 // describe (`describe NAME`) and call (`call NAME`). `tools` and `describe` answer from the
 // bundled snapshot in cli/catalog.js with no account and no network; `--refresh` reads the
 // live catalog instead. Output is JSON whenever stdout is not a terminal or --json is given,
-// and one error shape ({ error: { code, message, next } }) on every failure.
-const USAGE = 'tools [TOOLSET] [--json] [--refresh] | describe NAME [--examples] [--output-schema] [--json] [--refresh] | call NAME [--args JSON | --file FILE | --set PATH=VALUE ...] [--dry-run] [-y] [--json]';
+// and structured public errors. JSON preserves the public envelope; terminal rendering can
+// supply local guidance when the server has none.
+const USAGE = 'tools [TOOLSET] [--json] [--refresh] | describe NAME [--examples] [--output-schema] [--json] [--refresh] | schema NAME [FIELD.PATH] [--json] | call NAME [--args JSON | --file FILE | --set PATH=VALUE ...] [--dry-run] [-y] [--json]';
 const NAME = /^[a-z][a-z0-9_]*$/;
 const NEXT = {
   TOOL_NOT_FOUND: 'Run `agentlinkops tools` to list commands, or `agentlinkops tools TOOLSET` for one group.',
   INVALID_INPUT: 'Run `agentlinkops describe NAME` for the exact input schema.',
+  SCHEMA_PATH_NOT_FOUND: 'Run `agentlinkops schema NAME` for the top level, or drill a listed child path.',
   INSUFFICIENT_SCOPE: 'This credential lacks a scope the command needs; request it through your connection or a new project-scoped key.',
   NO_CLOUD_ORIGIN: 'Run `agentlinkops connect` or set AGENTLINKOPS_API_URL.',
   INVALID_CLOUD_ORIGIN: 'Cloud commands need an HTTPS origin without a path, for example https://app.agentlinkops.com.',
@@ -102,8 +105,20 @@ export async function commandsMain(argv, { cwd = process.cwd(), env = process.en
   const [command, name] = args._;
   const json = args.json === true || !isTTY;
   const fail = (code, message) => { if (json) err(errorJson(code, message, explain(code))); else err(`${message}\n${explain(code)}`); return 2; };
-  const allowed = { tools: ['_', 'json', 'refresh'], describe: ['_', 'json', 'refresh', 'examples', 'output-schema'], call: ['_', 'args', 'file', 'set', 'dry-run', 'json'] };
-  if (!allowed[command] || Object.keys(args).some(key => !allowed[command].includes(key)) || (command === 'tools' && args._.length > 2) || (command !== 'tools' && (args._.length !== 2 || !NAME.test(name)))) throw new ConfigError(USAGE);
+  const cloudFail = (error, context) => {
+    if (!error.publicError) return fail(error.code, `${context}: ${error.code}${error.status ? ` (${error.status})` : ''}`);
+    if (json) {
+      err(JSON.stringify({ error: error.publicError }));
+    }
+    else {
+      const next = [error.publicError.next, error.details?.next].find(value => typeof value === 'string' && value.trim()) ?? explain(error.code);
+      err(`${context}: ${error.code}${error.status ? ` (${error.status})` : ''}\n${error.serverMessage ?? error.code}\n${next}`);
+    }
+    return 2;
+  };
+  const allowed = { tools: ['_', 'json', 'refresh'], describe: ['_', 'json', 'refresh', 'examples', 'output-schema'], schema: ['_', 'json'], call: ['_', 'args', 'file', 'set', 'dry-run', 'json'] };
+  const positionalCount = command === 'tools' ? args._.length > 2 : command === 'schema' ? args._.length !== 2 && args._.length !== 3 : args._.length !== 2;
+  if (!allowed[command] || Object.keys(args).some(key => !allowed[command].includes(key)) || positionalCount || (command !== 'tools' && !NAME.test(name))) throw new ConfigError(USAGE);
   if (args.set?.length && (args.set.some(v => typeof v !== 'string') || args.args !== undefined || args.file !== undefined)) throw new ConfigError('--set cannot be combined with --args or --file');
   if (args.args !== undefined && args.file !== undefined) throw new ConfigError(USAGE);
 
@@ -139,7 +154,7 @@ export async function commandsMain(argv, { cwd = process.cwd(), env = process.en
       const live = await client.listCommands();
       commands = live.items.map(item => ({ ...item, readOnly: item.annotations?.readOnlyHint === true, admissionGated: false }));
     } catch (error) {
-      if (error instanceof CloudError) return fail(error.code, `catalog refresh: ${error.code}${error.status ? ` (${error.status})` : ''}`);
+      if (error instanceof CloudError) return cloudFail(error, 'catalog refresh');
       throw error;
     }
   }
@@ -160,6 +175,22 @@ export async function commandsMain(argv, { cwd = process.cwd(), env = process.en
     out(renderDescription(found, name, { examples: args.examples === true, outputSchema: args['output-schema'] === true, json }));
     return 0;
   }
+  if (command === 'schema') {
+    // DP-0059: the same drill the MCP exec tool serves, over the same bundled schema, so one
+    // grammar holds across surfaces: `schema monitor_link scope.target` prints that field.
+    const found = resolveName(commands, name);
+    if (!found) return fail('TOOL_NOT_FOUND', `No command named ${name}.`);
+    const path = args._[2] ?? null;
+    if (!path) { out(JSON.stringify({ name: found.name, schema: found.inputSchema }, null, 2)); return 0; }
+    const subschema = resolveSchemaPath(found.inputSchema, path);
+    if (!subschema) {
+      const parent = resolveSchemaPath(found.inputSchema, path.split('.').slice(0, -1).join('.')) ?? found.inputSchema;
+      const available = listAvailablePaths(parent);
+      return fail('SCHEMA_PATH_NOT_FOUND', `"${path}" is not a path in ${found.name}'s schema.${available.length ? ` Available here: ${available.join(', ')}.` : ''}`);
+    }
+    out(JSON.stringify({ name: found.name, path, schema: subschema }, null, 2));
+    return 0;
+  }
 
   // call
   const found = resolveName(commands, name);
@@ -177,7 +208,7 @@ export async function commandsMain(argv, { cwd = process.cwd(), env = process.en
     out(JSON.stringify(result, null, 2));
     return 0;
   } catch (error) {
-    if (error instanceof CloudError) return fail(error.code, `${canonical}: ${error.code}${error.status ? ` (${error.status})` : ''}${error.details ? ` ${JSON.stringify(error.details)}` : ''}`);
+    if (error instanceof CloudError) return cloudFail(error, canonical);
     throw error;
   }
 }

package/cli/connection.js

@@ -1,9 +1,12 @@
+import { acquireSyncLock } from './sync-lock.js';
 import { readFile, writeFile, rename, unlink, open } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { loadConfig, ConfigError } from './config.js';
 import { createClient } from './client.js';
 import { readLedger } from './ledger.js';
 import { resolveEnv } from './env.js';
+import { createOAuthCredentialStore } from './oauth-credentials.js';
+import { discoverOAuth, receiveOAuthConsent, exchangeOAuthCode } from './oauth-flow.js';
 
 export const SYNC_SCOPES = ['projects:read', 'watches:read', 'watches:write', 'events:read', 'exports:create'];
 
@@ -19,18 +22,33 @@ export function cloudConnection(config, env = process.env) {
     throw new ConfigError(`${sources.API_URL} disagrees with the saved cloud origin.`);
   if (new Set([config.cloud?.workspaceId, config.cloud?.workspace_id].filter(Boolean)).size > 1 || new Set([config.project?.id, config.cloud?.projectId, config.cloud?.project_id].filter(Boolean)).size > 1)
     throw new ConfigError('Saved cloud identity fields disagree.');
-  return { origin: values.API_URL || config.cloud?.origin,
-    token: values.TOKEN || values.API_KEY || config.cloud?.token,
+  const origin = values.API_URL || config.cloud?.origin;
+  const token = values.TOKEN || values.API_KEY || config.cloud?.token;
+  const auth = config.cloud?.auth;
+  if (auth !== undefined) {
+    if (!auth || auth.kind !== 'oauth' || token || Object.keys(auth).sort().join(',') !== 'clientId,credentialRef,issuer,kind,resource')
+      throw new ConfigError('Saved OAuth connection conflicts with an API key or has an invalid authentication mode.');
+    let resource, issuer;
+    try { resource = new URL(auth.resource); issuer = new URL(auth.issuer); } catch { throw new ConfigError('Saved OAuth binding is invalid.'); }
+    if (resource.href !== `${origin}/mcp` || issuer.protocol !== 'https:' || auth.issuer !== issuer.origin
+      || typeof auth.clientId !== 'string' || !auth.clientId || auth.clientId.length > 2048 || /[\s\x00-\x1f\x7f]/.test(auth.clientId)
+      || !/^oauth_[a-f0-9]{32}$/.test(auth.credentialRef ?? ''))
+      throw new ConfigError('Saved OAuth binding is invalid.');
+  }
+  return { origin, ...(auth ? { auth: { ...auth } } : {}),
+    token,
     tokenSource: values.TOKEN ? sources.TOKEN : values.API_KEY ? sources.API_KEY : null,
     workspaceId: config.cloud?.workspaceId || config.cloud?.workspace_id, projectId: config.project?.id || config.cloud?.projectId || config.cloud?.project_id };
 }
 
 export function keySetup(origin) {
-  return `Open ${origin}/app, select the workspace, then Agent access > Create API key. Select the project and scopes ${SYNC_SCOPES.join(', ')}. Supply the key through AGENTLINKOPS_TOKEN (AGENTLINKOPS_API_KEY also works; the LINKTRAIL_ spellings remain accepted during the pilot compatibility window), then rerun connect. MCP OAuth credentials remain in the MCP client.`;
+  return `Open ${origin}/app, select the workspace, then Agent access > Create API key. Select the project and scopes ${SYNC_SCOPES.join(', ')}. Supply the key through AGENTLINKOPS_TOKEN (AGENTLINKOPS_API_KEY also works; the LINKTRAIL_ spellings remain accepted during the pilot compatibility window), then rerun connect. For CLI OAuth on Linux, use connect --oauth with an existing public client; credentials stay in the user-owned POSIX-mode store. On other platforms, use OAuth in your MCP client. MCP clients manage their own credentials.`;
 }
 
 // Verify an existing project before saving only non-secret connection metadata.
-export async function connectMain(args, { cwd, env = process.env, out = console.log, fetchImpl = globalThis.fetch } = {}) {
+export async function connectMain(args, { cwd, env = process.env, out = console.log, fetchImpl = globalThis.fetch,
+  credentialStore = createOAuthCredentialStore(), oauth = { discoverOAuth, receiveOAuthConsent, exchangeOAuthCode },
+  onAuthorization = ({ authorizationUrl }) => out(`Authorize the connection: ${authorizationUrl}`), clientFactory = createClient } = {}) {
   const config = await loadConfig({ cwd });
   const connection = cloudConnection(config, env);
   const origin = args.origin || connection.origin || 'https://app.agentlinkops.com';
@@ -40,8 +58,13 @@ export async function connectMain(args, { cwd, env = process.env, out = console.
   try { parsed = new URL(origin); } catch { throw new ConfigError('connect --origin requires an HTTPS origin.'); }
   if (parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.search || parsed.hash || parsed.pathname !== '/')
     throw new ConfigError('connect --origin requires an HTTPS origin without a path.');
-  if (!connection.token) { out(keySetup(parsed.origin)); return 2; }
-  if (!/^lt_[0-9a-f]{64}$/.test(connection.token)) throw new ConfigError('Supply a complete API key through AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY.');
+  const oauthRequested = args.oauth === true || connection.auth?.kind === 'oauth';
+  if (args.oauth !== undefined && args.oauth !== true) throw new ConfigError('--oauth does not take a value.');
+  if (!oauthRequested && ['issuer', 'client-id', 'credential-ref'].some(key => args[key] !== undefined))
+    throw new ConfigError('OAuth options require --oauth.');
+  if (oauthRequested && connection.token) throw new ConfigError('Remove API-key credentials before selecting OAuth.');
+  if (!oauthRequested && !connection.token) { out(keySetup(parsed.origin)); return 2; }
+  if (!oauthRequested && !/^lt_[0-9a-f]{64}$/.test(connection.token)) throw new ConfigError('Supply a complete API key through AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY.');
   if (typeof workspaceId !== 'string' || !workspaceId || typeof projectId !== 'string' || !projectId)
     throw new ConfigError('connect requires --workspace ID and --project-id ID from the existing cloud project.');
   if (config.cloud?.origin && new URL(config.cloud.origin).origin !== parsed.origin || connection.workspaceId && connection.workspaceId !== workspaceId || connection.projectId && connection.projectId !== projectId)
@@ -56,35 +79,74 @@ export async function connectMain(args, { cwd, env = process.env, out = console.
       throw new ConfigError('Selection must name existing ledger IDs in a valid ledger.');
     ledgerIds = [...new Set(ledgerIds)];
   }
-  const client = createClient({ origin: parsed.origin, token: connection.token, workspaceId, fetchImpl });
+  let auth = connection.auth, createdRef, committed = false;
+  if (oauthRequested) {
+    try { await credentialStore.checkAvailability?.(); }
+    catch (error) {
+      if (error?.code !== 'OAUTH_CREDENTIAL_STORAGE_UNSUPPORTED') throw error;
+      throw Object.assign(new ConfigError('CLI OAuth credential storage is not supported on this platform. Use an API-key connection or OAuth in your MCP client until native custody is verified.'), {code: error.code});
+    }
+    const issuer = args.issuer || auth?.issuer, clientId = args['client-id'] || auth?.clientId;
+    if (!issuer || !clientId) throw new ConfigError('OAuth requires --issuer URL and --client-id ID for an existing public client.');
+    const binding = { issuer, resource: `${parsed.origin}/mcp`, clientId };
+    if (auth && (auth.issuer !== issuer || auth.clientId !== clientId || auth.resource !== binding.resource
+      || args['credential-ref'] && args['credential-ref'] !== auth.credentialRef))
+      throw new ConfigError('OAuth binding changed; use a separate ledger.');
+    const credentialRef = args['credential-ref'] || auth?.credentialRef;
+    if (credentialRef) {
+      await credentialStore.read(credentialRef, binding);
+      auth = { kind: 'oauth', ...binding, credentialRef };
+    } else {
+      const scopes = [...SYNC_SCOPES, 'offline_access'];
+      const plan = await oauth.discoverOAuth({ origin: parsed.origin, issuer, clientId, scopes, fetchImpl });
+      const authorization = await oauth.receiveOAuthConsent({ plan, scopes, onAuthorization });
+      const tokens = await oauth.exchangeOAuthCode({ plan, authorization, scopes, fetchImpl });
+      createdRef = await credentialStore.create(binding, tokens);
+      auth = { kind: 'oauth', ...binding, credentialRef: createdRef };
+    }
+  }
+  try {
+  const client = clientFactory({ origin: parsed.origin, token: connection.token, ...(auth ? {auth, credentialStore} : {}), workspaceId, projectId, fetchImpl });
   const account = await client.getWorkspace();
   if (account.workspace?.id !== workspaceId) throw new ConfigError('Cloud workspace does not match the selected workspace.');
-  const missing = SYNC_SCOPES.filter(scope => !account.access?.scopes?.includes(scope));
+  // MCP readback does not expose an authoritative effective write grant.
+  const missing = auth ? [] : SYNC_SCOPES.filter(scope => !account.access?.scopes?.includes(scope));
   if (missing.length) throw new ConfigError(`Key lacks sync scopes: ${missing.join(', ')}.`);
   const project = await client.getProject(projectId);
   if (project.id !== projectId || project.workspace_id !== workspaceId) throw new ConfigError('Cloud project does not match the selected workspace.');
-  const lockPath = join(config.dir, 'sync.lock');
-  const lock = await open(lockPath, 'wx');
+  const lock = await acquireSyncLock(config.dir, 'connect');
   const file = join(config.dir, 'config.json'), temporary = join(config.dir, `.connect-${crypto.randomUUID()}.tmp`);
   try {
     const before = await readFile(file, 'utf8');
     const saved = JSON.parse(before);
     const savedIdentity = cloudConnection(saved, {});
+    if (JSON.stringify(savedIdentity.auth ?? null) !== JSON.stringify(connection.auth ?? null))
+      throw new ConfigError('OAuth connection changed during verification; retry without replacing its credential binding.');
     if (savedIdentity.workspaceId && savedIdentity.workspaceId !== workspaceId || savedIdentity.projectId && savedIdentity.projectId !== projectId)
       throw new ConfigError('This ledger is connected to another workspace or project; use a separate ledger to preserve its cursors and mapping.');
     if (saved.cloud?.origin && new URL(saved.cloud.origin).origin !== parsed.origin)
       throw new ConfigError('This ledger is connected to another origin; use a separate ledger to preserve its cursors and mapping.');
     saved.cloud = { ...saved.cloud, origin: parsed.origin, workspaceId };
+    if (auth) saved.cloud.auth = auth;
+    else delete saved.cloud.auth;
     if (ledgerIds !== undefined) saved.cloud.ledgerIds = ledgerIds;
     delete saved.cloud.token;
     saved.project = { ...saved.project, id: projectId };
     await writeFile(temporary, JSON.stringify(saved, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
     if (await readFile(file, 'utf8') !== before) throw new ConfigError('Connection configuration changed; retry.');
     await rename(temporary, file);
+    committed = true;
   } finally {
     await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; });
-    await lock.close(); await unlink(lockPath);
+    await lock.release();
   }
-  out(`Verified workspace ${workspaceId}, project ${projectId}. Saved connection metadata; keep the key in the environment. Run agentlinkops sync --dry-run to review uploads, or agentlinkops sync --pull-only to retrieve history.`);
+  out(auth
+    ? `Verified workspace ${workspaceId}, project ${projectId}. Saved OAuth credential reference; write permission remains unverified. Run agentlinkops sync --pull-only to retrieve history.`
+    : `Verified workspace ${workspaceId}, project ${projectId}. Saved connection metadata; keep the key in the environment. Run agentlinkops sync --dry-run to review uploads, or agentlinkops sync --pull-only to retrieve history.`);
   return 0;
+  } catch (error) {
+    // A failed connection must not strand a newly created local secret.
+    if (createdRef && !committed) await credentialStore.remove(createdRef, {issuer: auth.issuer, resource: auth.resource, clientId: auth.clientId}).catch(() => {});
+    throw error;
+  }
 }

package/cli/doctor.js

@@ -19,6 +19,7 @@ import { loadConfig, setNoticeSink } from './config.js';
 import { readLedger } from './ledger.js';
 import { readReceipts } from './receipts.js';
 import { readState, writeState } from './state.js';
+import { acquireSyncLock } from './sync-lock.js';
 import { createClient, CloudError } from './client.js';
 import { cloudConnection } from './connection.js';
 import { validatePublicUrl, parseLinks, transitionState, checkObservationKind } from '../src/verifier/index.js';
@@ -112,9 +113,9 @@ export async function probeCloud({ origin, fetchImpl, timeoutMs = 5000 }) {
  * uses. Scope is a server-side fact, so this read (a plain watch listing, metered as none) is
  * the only honest answer to "is this token good for anything here".
  */
-export async function probeToken({ origin, token, workspaceId, fetchImpl }) {
+export async function probeToken({ origin, token, auth, workspaceId, projectId, fetchImpl }) {
   try {
-    await createClient({ origin, token, workspaceId, fetchImpl }).listWatches({ limit: 1 });
+    await createClient({ origin, token, auth, workspaceId, projectId, fetchImpl }).listWatches({ limit: 1 });
     return { verified: true };
   } catch (error) {
     if (error instanceof CloudError) return { verified: false, code: error.code, status: error.status, scope: error.details?.scope ?? null };
@@ -214,15 +215,15 @@ export async function doctorMain(argv = [], { cwd = process.cwd(), out = console
   // Token: presence, shape, and — only when the cloud just proved reachable — whether the
   // cloud accepts it. The value itself is never printed, hashed or measured here.
   const token = connection.token || null;
-  const source = connection.tokenSource ? `the environment (${connection.tokenSource})` : `${config.dirName}/config.json (cloud.token)`;
-  if (!token) {
+  const source = connection.auth ? 'the private OAuth credential store' : connection.tokenSource ? `the environment (${connection.tokenSource})` : `${config.dirName}/config.json (cloud.token)`;
+  if (!token && !connection.auth) {
     if (origin) {
       checks.push({ status: 'fail', name: 'token', detail: 'no token is set; sync and receive need one',
         fix: 'run agentlinkops connect for the app API-key setup path; supply AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY in the environment' });
     } else {
       checks.push({ status: 'skip', name: 'token', detail: 'no token (and no cloud configured)' });
     }
-  } else if (!TOKEN_SHAPE.test(token)) {
+  } else if (!connection.auth && !TOKEN_SHAPE.test(token)) {
     checks.push({ status: 'fail', name: 'token', detail: `set in ${source} but it does not look like an AgentLinkOps API key (lt_ plus 64 hex characters)`,
       fix: 'copy the full key without truncation or line breaks; the key itself is never printed here' });
   } else if (!origin) {
@@ -230,15 +231,20 @@ export async function doctorMain(argv = [], { cwd = process.cwd(), out = console
   } else {
     const cloudLine = checks.find(check => check.name === 'cloud');
     if (cloudLine?.status === 'ok') {
-      const probed = await probeToken({ origin, token, workspaceId: config.cloud?.workspaceId, fetchImpl });
+      const probed = await probeToken({ ...connection, fetchImpl });
       if (probed.verified) {
         record.token = { ok: true };
         checks.push({ status: 'ok', name: 'token', detail: `set in ${source}; the cloud accepted it (watches:read works)` });
       } else if (probed.verified === false) {
         record.token = { ok: false, code: probed.code };
-        const fix = probed.code === 'INSUFFICIENT_SCOPE' ? `issue a key carrying ${probed.scope ?? 'watches:read'}`
+        const fix = probed.code === 'INSUFFICIENT_SCOPE' ? connection.auth
+          ? `authorize ${probed.scope ?? 'watches:read'} through the configured OAuth client and workspace grant`
+          : `issue a key carrying ${probed.scope ?? 'watches:read'}`
           : probed.code === 'WORKSPACE_DENIED' ? `check cloud.workspaceId in ${config.dirName}/config.json against the workspace the key belongs to`
-          : probed.code === 'UNAUTHORIZED' ? 'issue a fresh key (this one is invalid or expired) and update where it is set'
+          : probed.code === 'UNAUTHORIZED' ? connection.auth
+            ? 'reconnect with the configured OAuth issuer and public client; do not repeat an unresolved write'
+            : 'issue a fresh key (this one is invalid or expired) and update where it is set'
+          : probed.code === 'OAUTH_CREDENTIAL_STORAGE_UNSUPPORTED' ? 'use an API-key connection or OAuth in your MCP client until native credential custody is verified'
           : 'sync will fail the same way; act on the code above';
         const detail = probed.code === 'INSUFFICIENT_SCOPE' ? `the cloud accepted it but scope ${probed.scope ?? 'watches:read'} is missing`
           : probed.code === 'WORKSPACE_DENIED' ? 'the credential belongs to a different workspace'
@@ -287,12 +293,21 @@ export async function doctorMain(argv = [], { cwd = process.cwd(), out = console
   // of failing doctor twice.
   if (probed) {
     const cloudLine = checks.find(check => check.name === 'cloud');
+    let writer = null;
     try {
-      const current = state ?? await readState(config.paths.state);
+      writer = await acquireSyncLock(config.dir, 'doctor');
+      // Diagnostics may await the network while sync commits. Merge only our record
+      // into fresh state under the same writer gate; the early snapshot is stale.
+      const current = await readState(config.paths.state);
       await writeState(config.paths.state, { ...current, doctor: record });
       if (cloudLine) cloudLine.detail += ' (recorded in state.json)';
     } catch (error) {
       if (cloudLine) cloudLine.detail += ` (result NOT recorded: ${error.message})`;
+    } finally {
+      if (writer) {
+        try { await writer.release(); }
+        catch (error) { if (cloudLine) cloudLine.detail += ` (writer release failed: ${error.message})`; }
+      }
     }
   }
 

package/cli/gsc-browser.js

@@ -15,7 +15,7 @@ Files must be new. CSV exports are limited to 20 MiB and include a receipt.
 Review column mapping before importing. The export does not prove links are live.`;
 
 // This factory also runs in Playwriter's CommonJS sandbox. Keep dependencies explicit.
-export function createGscBrowserExporter({ fs, path, createHash, parseCsv }) {
+export function createGscBrowserExporter({ fs, path, createHash, parseCsv, platform = process.platform }) {
   const limit = 20 * 1024 * 1024;
   const fail = (code, message) => Object.assign(new Error(message), { code, exitCode: 2 });
   async function bounded(promise, milliseconds) {
@@ -82,7 +82,7 @@ export function createGscBrowserExporter({ fs, path, createHash, parseCsv }) {
     const report = new URL('https://search.google.com/search-console/links');
     report.searchParams.set('resource_id', property);
     report.searchParams.set('hl', 'en');
-    let download, ownedOutput = false, ownedReceipt = false;
+    let download, outputHandle, receiptHandle, ownedOutput = false, ownedReceipt = false;
     const receive = item => { if (!download) download = item; };
     try {
       await page.goto(report.href, { waitUntil: 'domcontentloaded', timeout: 20000 });
@@ -190,14 +190,27 @@ export function createGscBrowserExporter({ fs, path, createHash, parseCsv }) {
         source_column: sourceHeader, target_mapping_required: true,
         sampled: true, current_link_status: 'unverified',
       };
-      await fs.writeFile(outputPath, Buffer.concat(chunks), { flag: 'wx', mode: 0o600 }); ownedOutput = true;
-      await fs.writeFile(receiptPath, `${JSON.stringify(receipt, null, 2)}\n`, { flag: 'wx', mode: 0o600 }); ownedReceipt = true;
+      outputHandle = await fs.open(outputPath, 'wx', 0o600); ownedOutput = true;
+      receiptHandle = await fs.open(receiptPath, 'wx', 0o600); ownedReceipt = true;
+      for (const handle of [outputHandle, receiptHandle]) {
+        const info = await handle.stat();
+        if (!info.isFile() || (platform !== 'win32' && (info.mode & 0o7777) !== 0o600)) {
+          throw fail('private_storage_required', 'GSC exports require private files with mode 0600. Choose a filesystem that enforces private permissions.');
+        }
+      }
+      await outputHandle.writeFile(Buffer.concat(chunks));
+      await receiptHandle.writeFile(`${JSON.stringify(receipt, null, 2)}\n`);
+      await outputHandle.close(); outputHandle = undefined;
+      await receiptHandle.close(); receiptHandle = undefined;
       return receipt;
     } catch (error) {
       await download?.cancel?.().catch(() => {});
+      await outputHandle?.close().catch(() => {});
+      await receiptHandle?.close().catch(() => {});
       if (ownedOutput) await fs.unlink(outputPath).catch(() => {});
       if (ownedReceipt) await fs.unlink(receiptPath).catch(() => {});
       if (error.exitCode === 2) throw error;
+      if (error.code === 'EEXIST') throw fail('output_exists', 'The output or receipt file already exists. Choose a new path.');
       throw fail('browser_export_failed', 'GSC export failed. Check your browser session and retry.');
     } finally {
       page.off('download', receive);
@@ -206,7 +219,7 @@ export function createGscBrowserExporter({ fs, path, createHash, parseCsv }) {
   };
 }
 
-export const exportGscLinks = createGscBrowserExporter({ fs, path, createHash, parseCsv });
+export const exportGscLinks = createGscBrowserExporter({ fs, path, createHash, parseCsv, platform: process.platform });
 
 export async function gscLinksMain(argv, { cwd = process.cwd(), out = console.log, execFileImpl = promisify(execFile) } = {}) {
   const args = parseArgs(argv);
@@ -221,7 +234,7 @@ export async function gscLinksMain(argv, { cwd = process.cwd(), out = console.lo
   const scratch = await fs.mkdtemp(path.join(tmpdir(), 'agentlinkops-gsc-'));
   try {
     // Pass source/config as a file argument, never interpolate a shell command.
-    const script = `const CsvError = ${CsvError.toString()};\nconst parseCsv = ${parseCsv.toString()};\nconst exportLinks = (${createGscBrowserExporter.toString()})({fs:require('node:fs').promises,path:require('node:path'),createHash:require('node:crypto').createHash,parseCsv});\nconst config = ${JSON.stringify({ property: args.property, outputPath, kind: args.kind ?? 'latest' })};\nconst exportPage = await context.newPage();\ntry { const receipt = await exportLinks({...config,page:exportPage}); console.log('AGENTLINKOPS_GSC_RECEIPT '+JSON.stringify(receipt)); } catch(error) { console.log('AGENTLINKOPS_GSC_ERROR '+JSON.stringify({code:error.code||'browser_export_failed',message:error.message})); } finally { await exportPage.close(); }\n`;
+    const script = `const CsvError = ${CsvError.toString()};\nconst parseCsv = ${parseCsv.toString()};\nconst exportLinks = (${createGscBrowserExporter.toString()})({fs:require('node:fs').promises,path:require('node:path'),createHash:require('node:crypto').createHash,parseCsv,platform:require('node:os').platform()});\nconst config = ${JSON.stringify({ property: args.property, outputPath, kind: args.kind ?? 'latest' })};\nconst exportPage = await context.newPage();\ntry { const receipt = await exportLinks({...config,page:exportPage}); console.log('AGENTLINKOPS_GSC_RECEIPT '+JSON.stringify(receipt)); } catch(error) { console.log('AGENTLINKOPS_GSC_ERROR '+JSON.stringify({code:error.code||'browser_export_failed',message:error.message})); } finally { await exportPage.close(); }\n`;
     const scriptPath = path.join(scratch, 'export.js');
     await fs.writeFile(scriptPath, script, { mode: 0o600 });
     let stdout;

package/cli/ledger.js

@@ -1,3 +1,4 @@
+import { acquireSyncLock } from './sync-lock.js';
 // The ledger: intent, human-owned, one JSON object per line.
 //
 // Reading is deliberately forgiving of everything except silence. A line that does not parse,
@@ -5,7 +6,7 @@
 // set — never dropped quietly. A tool that discards a customer's row and carries on produces a
 // number that is wrong in a way they discover months later.
 import { readFile, writeFile, mkdir, rename, open, unlink } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import {lifecycleDeal,emptyDeal} from '../shared/lifecycle-contract.js';
 
 export const INTENTS = Object.freeze(['wanted', 'expected', 'retired']);
@@ -189,11 +190,7 @@ export async function writeLedger(path, entries) {
 
 /** Read, validate and replace under one lock. A malformed row prevents every mutation. */
 export async function mutateLedger(path, update) {
-  const lockPath = `${path}.lock`;
-  const lock = await open(lockPath, 'wx').catch(error => {
-    if (error.code === 'EEXIST') throw new Error('Ledger is being updated by another process.');
-    throw error;
-  });
+  const lock = await acquireSyncLock(dirname(path), 'ledger-update', {markerName: `${basename(path)}.lock`});
   try {
     const ledger = await readLedger(path);
     if (ledger.missing) throw new Error('Ledger does not exist.');
@@ -201,7 +198,7 @@ export async function mutateLedger(path, update) {
     const result = await update(ledger.entries);
     await writeLedger(path, result);
     return result;
-  } finally { await lock.close(); await unlink(lockPath); }
+  } finally { await lock.release(); }
 }
 
 /**

package/cli/lifecycle.js

@@ -13,7 +13,7 @@ agentlinkops lifecycle report [--from YYYY-MM-DD] [--to YYYY-MM-DD]
 Uses the connected project. Deal costs are integer currency minor units. Null clears a field; costMinor and currency must be set or cleared together. Clear removes deal metadata, not the watch. Renew retains due events without sending a message. --decimal-cost reads cost_amount as an exact decimal string and cost_currency using the supported currency scale. sync --lifecycle pulls a deal mirror without editing the ledger.`;
 const fail=message=>{throw new ConfigError(message);};
 const integer=(value,name)=>{if(typeof value!=='string'||!/^\d+$/.test(value)||!Number.isSafeInteger(Number(value)))fail(`${name} requires a nonnegative integer`);return Number(value);};
-export async function lifecycleMain(args,{cwd=process.cwd(),env=process.env,out=console.log,fetchImpl=globalThis.fetch}={}){
+export async function lifecycleMain(args,{cwd=process.cwd(),env=process.env,out=console.log,err=console.error,fetchImpl=globalThis.fetch}={}){
  if(args.help){out(LIFECYCLE_CLI_HELP);return 0;}
  const action=args._?.[1],allowed={get:[],update:['revision','deal','decimal-cost'],clear:['revision'],renew:['limit'],report:['from','to']}[action];
  if(!allowed||args.tag?.length||Object.keys(args).some(key=>!['_','tag',...allowed].includes(key)))fail(LIFECYCLE_CLI_HELP);
@@ -36,5 +36,8 @@ export async function lifecycleMain(args,{cwd=process.cwd(),env=process.env,out=
  if(action==='renew'){name='record_lifecycle_renewals';schema=C.lifecycleRenewInput;output=C.lifecycleRenewOutput;if(args.limit!==undefined)input.limit=integer(args.limit,'--limit');}
  if(action==='report'){name='get_lifecycle_report';schema=C.lifecycleReportInput;output=C.lifecycleReportOutput;for(const key of ['from','to'])if(args[key]!==undefined)input[key]=args[key];}
  const parsed=schema.safeParse(input);if(!parsed.success)fail('Invalid lifecycle dates, fields or bounds');
- const result=await createClient({...connection,fetchImpl}).callCommand(name,parsed.data),checked=output.safeParse(result);if(!checked.success)fail('Invalid lifecycle service response');out(JSON.stringify(checked.data,null,2));return 0;
+ let result;
+ try{result=await createClient({...connection,fetchImpl}).callCommand(name,parsed.data);}
+ catch(error){if(!error.publicError)throw error;err(JSON.stringify({error:error.publicError}));return 2;}
+ const checked=output.safeParse(result);if(!checked.success)fail('Invalid lifecycle service response');out(JSON.stringify(checked.data,null,2));return 0;
 }