agentlinkops 0.6.8 → 0.6.10

package/cli/local-result.js

@@ -1,8 +1,9 @@
+import { acquireSyncLock } from './sync-lock.js';
 // Portable, accountless first result and explicit repository adoption. No hosted client.
 import { createHash, randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { readFile, writeFile, mkdir, open, rename, unlink } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { matchesTarget } from '../src/verifier/url.js';
 import { validatePublicUrl } from '../src/verifier/index.js';
 import { runCheck } from './check.js';
@@ -124,8 +125,7 @@ export async function adoptLocalResult(config, supplied, { intent = 'wanted', af
   if (!['wanted', 'expected'].includes(intent)) throw new Error('adoption intent must be wanted or expected');
   const result = validateLocalResult(supplied);
   if (new Set([config.paths.ledger, config.paths.observations, config.paths.state]).size !== 3) throw new Error('adoption destinations must be distinct');
-  const lockPath = `${config.paths.ledger}.lock`;
-  const lock = await open(lockPath, 'wx');
+  const lock = await acquireSyncLock(dirname(config.paths.ledger), 'adopt-result', {markerName: `${basename(config.paths.ledger)}.lock`});
   const journalPath = join(config.dir, 'adopt-result-transaction.json');
   try {
     const pending = await textAt(journalPath);
@@ -157,5 +157,5 @@ export async function adoptLocalResult(config, supplied, { intent = 'wanted', af
     await writeFile(journalPath, JSON.stringify({ version: 1, parts }), { flag: 'wx' });
     await finishAdoption(journalPath, { version: 1, parts }, config, afterWrite);
     return { result_id: result.result_id, ledger_id: entry.id, created: !matches[0], observation_added: true };
-  } finally { await lock.close(); await unlink(lockPath); }
+  } finally { await lock.release(); }
 }

package/cli/main.js

@@ -1,3 +1,4 @@
+import { acquireSyncLock } from './sync-lock.js';
 import {lifecycleMain} from './lifecycle.js';
 import {admissionMain} from './admission.js';
 import { commandsMain } from './commands.js';
@@ -77,20 +78,20 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
                                             .agentlinkops/citations/; live engines need
                                             engine-specific setup; the mock engine makes no paid calls
   agentlinkops receive --body FILE --headers FILE   signed notification; authenticated pull
-  agentlinkops connect --workspace ID --project-id ID [--origin URL] [--selection FILE]
+  agentlinkops connect --workspace ID --project-id ID [--origin URL] [--selection FILE] [--oauth --issuer URL --client-id ID [--credential-ref REF]]
   agentlinkops tools [TOOLSET] [--json] [--refresh]   cloud commands by toolset (offline snapshot;
                                             --refresh reads the live catalog)
   agentlinkops describe NAME [--examples] [--output-schema] [--json]  one command's exact schema
   agentlinkops call NAME [--args JSON | --file FILE | --set PATH=VALUE ...] [--dry-run] [-y]
                                             run a cloud command (retired names still resolve)
   agentlinkops agent setup [--client ID ...] [--scope project|user] [--origin URL] [--dry-run]
-                                            install the skill pack and the right MCP view for each
-                                            detected agent client (Claude Code, Codex, Cursor,
-                                            Gemini CLI, Hermes); stores no credential
+                                            core connection/reference and the right MCP view;
+                                            optional --skill ID ... / --recipe ID ... / --all-skills;
+                                            stores no credential; preserves customer instructions
   agentlinkops agent status                 what is installed where
-  agentlinkops agent remove [--scope project|user] [--apply] [--json]
+  agentlinkops agent remove [--skill ID ...] [--recipe ID ...] [--scope project|user] [--apply] [--json]
   agentlinkops agent recover [--scope project|user] [--apply] [--json]
-  agentlinkops sync [--push-only] [--pull-only] [--dry-run] [--include-wanted] [--lifecycle]
+  agentlinkops sync [--push-only] [--pull-only] [--dry-run] [--include-wanted] [--lifecycle] [--recover-cursors]
                                             AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY
   agentlinkops check [--filter TEXT] [--all] [--json] [--fail-on-unknown]
   agentlinkops doctor                       verify ledger, verifier, cloud reachability, token
@@ -133,7 +134,7 @@ function reportProblems(problems, what, out) {
   if (problems.length > 20) out(`  … and ${problems.length - 20} more`);
 }
 
-export async function main(argv = process.argv.slice(2), { cwd = process.cwd(), out = console.log, err = console.error, env = process.env, fetchImpl = globalThis.fetch } = {}) {
+export async function main(argv = process.argv.slice(2), { cwd = process.cwd(), out = console.log, err = console.error, env = process.env, fetchImpl = globalThis.fetch, afterHistoryPersisted, afterStatePersisted } = {}) {
   if (argv[0] === 'gsc-links') return await gscLinksMain(argv, { cwd, out });
   // Citation watches keep their own files under .agentlinkops/citations/ and never
   // touch the link ledger, so they dispatch before its requirement like context does.
@@ -147,17 +148,19 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
 
   let syncLock = null;
   try {
-    if (command === 'lifecycle') return await lifecycleMain(args,{cwd,env,fetchImpl,out});
+    if (args['recover-cursors'] !== undefined && (command !== 'sync' || args['recover-cursors'] !== true || args['pull-only'] !== true || args['push-only']))
+      throw new ConfigError('Cursor recovery requires agentlinkops sync --pull-only --recover-cursors; it performs no remote writes.');
+    if (command === 'lifecycle') return await lifecycleMain(args,{cwd,env,fetchImpl,out,err});
     if (command === 'admission') { const config=await loadConfig({cwd}); return await admissionMain(argv.slice(1),{client:createClient({...cloudConnection(config,env),fetchImpl}),out,err}); }
     if (command === 'disavow') return await disavowMain(args,{cwd,env,fetchImpl,out});
     if (command === 'index') return await indexMain(args,{cwd,env,fetchImpl,out});
     if (command === 'setup') return await setupPlanMain(argv, { cwd, out });
-    if (command === 'tools' || command === 'describe' || command === 'call') return await commandsMain(argv, { cwd, out, err, env, fetchImpl });
+    if (command === 'tools' || command === 'describe' || command === 'schema' || command === 'call') return await commandsMain(argv, { cwd, out, err, env, fetchImpl });
     if (command === 'skill') return await skillMain(argv, { out });
     if (command === 'agent') return await agentMain(argv, { cwd, out, err });
     if (command === 'connect') {
-      if (args._.length !== 1 || args.tag.length || Object.keys(args).some(key => !['_', 'tag', 'origin', 'workspace', 'project-id', 'selection'].includes(key))) throw new ConfigError('connect --workspace ID --project-id ID [--origin URL] [--selection FILE]');
-      return await connectMain(args, { cwd, out });
+      if (args._.length !== 1 || args.tag.length || Object.keys(args).some(key => !['_', 'tag', 'origin', 'workspace', 'project-id', 'selection', 'oauth', 'issuer', 'client-id', 'credential-ref'].includes(key))) throw new ConfigError('connect --workspace ID --project-id ID [--origin URL] [--selection FILE] [--oauth --issuer URL --client-id ID [--credential-ref REF]]');
+      return await connectMain(args, { cwd, out, env, fetchImpl });
     }
     if (command === 'check' && (args.source !== undefined || args.target !== undefined)) {
       if (typeof args.source !== 'string' || typeof args.target !== 'string') throw new ConfigError('check requires both --source URL and --target URL');
@@ -329,9 +332,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
 
     const config = await loadConfig({ cwd });
     if (['sync','receive','check','compact','adopt-result'].includes(command) && !(command === 'sync' && args['dry-run'])) {
-      const lockPath = join(config.dir, 'sync.lock');
-      try { syncLock = { handle: await open(lockPath, 'wx'), path: lockPath }; }
-      catch (error) { if (error.code === 'ENOENT') throw new ConfigError('no ledger here — run `agentlinkops init` first'); if (error.code === 'EEXIST') throw new ConfigError('sync writer already locked; retry delivery after it finishes'); throw error; }
+      syncLock = await acquireSyncLock(config.dir, command);
     }
     if (command === 'adopt-result') {
       if (args._.length !== 2 || Object.keys(args).some(key => !['_', 'intent', 'tag'].includes(key)) || args.tag.length) throw new ConfigError('adopt-result FILE [--intent wanted|expected]');
@@ -506,7 +507,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
         for (const change of found.slice(0, 100)) out(`  ${change.at.slice(0, 10)}  ${change.from} -> ${change.to}  ${change.id}`);
         return 0;
       }
-      const groups = { appeared: 'appeared', lost: 'LOST', cannot_say: 'cannot say', never_checked: 'never checked' };
+      const groups = { appeared: 'appeared', lost: 'LOST', suspected_missing: 'suspected missing', cannot_say: 'cannot say', never_checked: 'never checked' };
       for (const [kind, label] of Object.entries(groups)) {
         const rows = found.filter(item => item.kind === kind);
         if (!rows.length) continue;
@@ -524,7 +525,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       if (command === 'receive') {
         if (!args.body || !args.headers) throw new ConfigError('receive --body RAW_BODY_FILE --headers HEADERS_JSON_FILE');
         verifyDelivery({ body: await readFile(String(args.body), 'utf8'), headers: JSON.parse(await readFile(String(args.headers), 'utf8')),
-          secret: readEnv(process.env, 'WEBHOOK_SECRET').value, workspaceId: config.cloud?.workspaceId });
+          secret: readEnv(env, 'WEBHOOK_SECRET').value, workspaceId: config.cloud?.workspaceId });
         args['pull-only'] = true;
         args['push-only'] = false;
       }
@@ -533,11 +534,11 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       if(args.lifecycle&&args['push-only'])throw new ConfigError('--lifecycle requires a pull; omit --push-only.');
       const selection = { includeWanted: args['include-wanted'] === true, ledgerIds: config.cloud?.ledgerIds ?? null };
       if (args['dry-run']) { out(JSON.stringify({ network: false, rows: args['pull-only'] ? [] : syncPlan(ledger.entries, state, selection) }, null, 2)); return 0; }
-      const connection = cloudConnection(config);
+      const connection = cloudConnection(config, env);
       if (!connection.origin) { err('no cloud origin — run agentlinkops connect'); return 2; }
-      if (!connection.token) { err(keySetup(connection.origin)); return 2; }
+      if (!connection.token && !connection.auth) { err(keySetup(connection.origin)); return 2; }
       if (!connection.projectId) { err('no project id — run agentlinkops connect'); return 2; }
-      const client = createClient(connection);
+      const client = createClient({ ...connection, fetchImpl });
       let next = { ...state };
       let pushFailed = false;
       if (!args['pull-only']) {
@@ -549,28 +550,38 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
         pushFailed = pushed.failed.length > 0;
       }
       if (!args['push-only']) {
-        const pulled = await pullEvents(client, next, {
-          onSnapshot: async snapshot => {
-            // A resync writes the snapshot beside the mirror rather than into the ledger: the
-            // cloud is a mirror of the customer's file and never the other way round.
-            await writeFile(join(config.dir, `snapshot-${Date.now()}.json`), `${JSON.stringify(snapshot, null, 1)}\n`, 'utf8');
+        const snapshots = [];
+        const recovery = {
+          recoverInvalidCursor: args['recover-cursors'] === true,
+          onSnapshot: async (snapshot, feed) => {
+            const path = join(config.dir, `snapshot-${feed}-${Date.now()}-${crypto.randomUUID()}.json`);
+            await writeFile(path, `${JSON.stringify(snapshot, null, 1)}\n`, {encoding: 'utf8', flag: 'wx', mode: 0o600});
+            snapshots.push({feed, path});
           },
+        };
+        const pulled = await pullEvents(client, next, {
+          ...recovery,
         });
         // Two feeds, two cursors. They are pulled separately and written separately, so an
         // expiry on one cannot move the other.
-        const targets = await pullTargetEvents(client, next);
+        const targets = await pullTargetEvents(client, next, recovery);
         const index = await watchIndex(client, next);
         if(args.lifecycle)next.lifecycle=await pullLifecycleMirrors(client,next,{projectId:connection.projectId,index,ledgerIds:selection.ledgerIds??ledger.entries.map(entry=>entry.id)});
         const { fresh, duplicates } = await persistPulledHistory(config, pulled.events, targets.events, index);
+        await afterHistoryPersisted?.();
         next.cursors = { ...(next.cursors ?? {}), events: pulled.cursor, target_events: targets.cursor };
         next.gaps = [...(next.gaps ?? []), ...pulled.gaps, ...targets.gaps];
         out(`pulled ${pulled.events.length} event(s) over ${pulled.pages} page(s), ${fresh.length} observation(s)${duplicates.length ? `, ${duplicates.length} already held` : ''}`);
         if (targets.events.length) out(`pulled ${targets.events.length} target event(s) over ${targets.pages} page(s)`);
         // A gap is stated, never inferred. An empty feed means nothing happened; an expired
         // cursor means something happened and is gone.
-        for (const gap of [...pulled.gaps, ...targets.gaps]) out(`  RESYNC ${gap.at}: ${gap.reason}; a snapshot was written to ${config.dir}`);
+        for (const gap of [...pulled.gaps, ...targets.gaps]) {
+          const snapshot = snapshots.find(item => item.feed === gap.feed);
+          out(`  RESYNC ${gap.at}: ${gap.reason}; ${snapshot ? `snapshot saved to ${snapshot.path}` : 'current-state snapshot applied'}`);
+        }
       }
       await writeState(config.paths.state, next);
+      await afterStatePersisted?.();
       return pushFailed ? 2 : 0;
     }
 
@@ -595,7 +606,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       if (args.json) { out(rows.map(row => JSON.stringify(row)).join('\n')); return summary.exitCode; }
       reportProblems(ledger.problems, 'ledger line(s)', out);
       for (const { entry, row } of summary.appeared) out(`APPEARED  ${entry.id}  ${entry.source}  (${row.occurrences} occurrence(s))`);
-      for (const { entry, row } of summary.failures) out(`LOST      ${entry.id}  ${entry.source}  [${row.reason}]`);
+      for (const { entry, row } of summary.failures) out(`ABSENT    ${entry.id}  ${entry.source}  [${row.reason}]`);
       out(`\n${JSON.stringify(summary.counts)}`);
       out(`${plural(changed.length, 'observation')} recorded, ${repeated.length} repeated an answer already on file`);
       if (summary.counts.unknown) {
@@ -609,9 +620,13 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
     return 2;
   } catch (error) {
     if (error instanceof ConfigError) { err(error.message); return 2; }
+    if (command === 'sync' && args['recover-cursors'] === true && error instanceof CloudError) {
+      err(JSON.stringify({error: {code: error.code, status: error.status, next: 'Keep this project ledger and its history. Resolve authorized read access for the configured project, then retry agentlinkops sync --pull-only --recover-cursors. Do not broaden grants or replay remote writes.'}}));
+      return 2;
+    }
     err(`agentlinkops: ${error?.message ?? error}`);
     return 2;
   } finally {
-    if (syncLock) { await syncLock.handle.close(); await unlink(syncLock.path); }
+    if (syncLock) await syncLock.release();
   }
 }

package/cli/mcp-client.js

@@ -0,0 +1,198 @@
+import {CloudError} from './cloud-error.js';
+import {createOAuthCredentialStore} from './oauth-credentials.js';
+import {discoverOAuth, refreshOAuthTokens} from './oauth-flow.js';
+import {restResponseContract} from '../shared/response-contract.js';
+import {SHAPES} from '../src/response-shaping.js';
+
+const sleepDefault = ms => new Promise(done => setTimeout(done, ms));
+const fail = (code, status = 400) => { throw new CloudError(code, status); };
+const ERROR_BYTES = 65536;
+const sensitive = (text, token) => typeof text === 'string' && (token && text.includes(token)
+  || /\blt_[a-f0-9]{64}\b|\b[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\b/.test(text));
+function publicError(value, token, depth = 0) {
+  if (depth > 8) return '[redacted]';
+  if (typeof value === 'string') return sensitive(value, token) ? '[redacted]' : value;
+  if (Array.isArray(value)) return value.slice(0, 100).map(item => publicError(item, token, depth + 1));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).slice(0, 100)
+    .filter(([key]) => !/token|authorization|password|secret|cookie|session/i.test(key))
+    .map(([key, item]) => [key, publicError(item, token, depth + 1)]));
+  return value;
+}
+async function boundedError(response) {
+  if (!response.body?.getReader) return null;
+  const reader = response.body.getReader(), chunks = []; let size = 0;
+  try {
+    while (true) {
+      const {value, done} = await reader.read(); if (done) break;
+      size += value.byteLength;
+      if (size > ERROR_BYTES) { await reader.cancel().catch(() => {}); return null; }
+      chunks.push(Buffer.from(value));
+    }
+    return JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(Buffer.concat(chunks, size)));
+  } catch { return null; } finally { reader.releaseLock(); }
+}
+const statusOf = error => (Number.isInteger(error.status) && error.status >= 400 && error.status <= 599 ? error.status : null) ?? ({INSUFFICIENT_SCOPE: 403, AGENT_APPROVAL_REQUIRED: 403,
+  GRANT_REVOKED: 401, UNAUTHORIZED: 401, CURSOR_EXPIRED: 410, RATE_LIMITED: 429,
+  QUOTA_EXCEEDED: 429, SERVICE_UNAVAILABLE: 503}[error.code]) ?? 400;
+function payloadOf(result) {
+  if (result?.structuredContent && typeof result.structuredContent === 'object') return result.structuredContent;
+  try { return JSON.parse(result?.content?.find(item => item.type === 'text')?.text); }
+  catch { fail('INVALID_RESPONSE', 502); }
+}
+function normalized(result, token) {
+  const data = payloadOf(result);
+  if (result?.isError) {
+    const error = publicError(data?.error, token);
+    if (!error || typeof error.code !== 'string' || !/^[A-Z][A-Z0-9_]{1,100}$/.test(error.code)) fail('INVALID_RESPONSE', 502);
+    throw new CloudError(error.code, statusOf(error), error.details ?? null, error.message ?? null,
+      error, {retryAfter: error.retryAfter ?? publicError(result.retryAfter, token) ?? null,
+        requestId: error.requestId ?? publicError(result.requestId, token) ?? null});
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) fail('INVALID_RESPONSE', 502);
+  return data;
+}
+function retryDelay(error, attempt, now) {
+  if (!(error instanceof CloudError) || ![0, 429, 503].includes(error.status)) return null;
+  if (error.status === 0 && !['CLOUD_NETWORK_ERROR', 'CLOUD_TIMEOUT'].includes(error.code)) return null;
+  const value = error.retryAfter;
+  if (value == null || value === '') return Math.min(5000, 250 * 2 ** (attempt - 1));
+  const delay = /^\d+$/.test(String(value).trim()) ? Number(value) * 1000 : Date.parse(value) - now();
+  return Number.isFinite(delay) && delay >= 0 && delay <= 5000 ? delay : null;
+}
+
+async function sdkClient({url, token, workspaceId, fetchImpl}) {
+  const {Client, StreamableHTTPClientTransport} = await import('@modelcontextprotocol/client');
+  const client = new Client({name: 'agentlinkops-cli', version: '0.6.10'});
+  const destination = new URL(url);
+  const transport = new StreamableHTTPClientTransport(destination, {
+    authProvider: {token: async () => token},
+    fetch: async (input, init = {}) => {
+      const target = new URL(typeof input === 'string' || input instanceof URL ? input : input.url);
+      if (target.href !== destination.href) fail('OAUTH_TOKEN_DESTINATION_MISMATCH');
+      const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
+      if (workspaceId) headers.set('X-Workspace-ID', workspaceId);
+      headers.set('User-Agent', 'agentlinkops-cli/0.6.10');
+      const response = await fetchImpl(input, {...init, headers, redirect: 'error', signal: AbortSignal.timeout(30000)});
+      if (response.redirected || response.status >= 300 && response.status < 400
+        || response.url && response.url !== destination.href) fail('OAUTH_TOKEN_DESTINATION_MISMATCH');
+      if (!response.ok) {
+        const data = await boundedError(response), error = publicError(data?.error, token);
+        const code = typeof error?.code === 'string' && /^[A-Z][A-Z0-9_]{1,100}$/.test(error.code)
+          ? error.code : `HTTP_${response.status}`;
+        throw new CloudError(code, response.status, error?.details ?? null,
+          error?.message ?? null, error ?? null,
+          {retryAfter: publicError(response.headers.get('Retry-After'), token),
+            requestId: error?.requestId ?? publicError(response.headers.get('X-Request-ID'), token)});
+      }
+      return response;
+    },
+  });
+  try { await client.connect(transport, {timeout: 30000}); return client; }
+  catch (error) { await client.close().catch(() => {}); throw error; }
+}
+
+export function createMcpClient({origin, auth, workspaceId, projectId, credentialStore,
+  createSdkClient = sdkClient, fetchImpl = globalThis.fetch, sleepImpl = sleepDefault, now = Date.now, resolveHost} = {}) {
+  let base, issuer;
+  try { base = new URL(origin); issuer = new URL(auth?.issuer); } catch { fail('OAUTH_CONFIG_INVALID'); }
+  if (base.protocol !== 'https:' || base.origin !== origin || issuer.protocol !== 'https:' || issuer.origin !== auth?.issuer
+    || auth?.kind !== 'oauth' || auth.resource !== `${origin}/mcp` || 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 ?? '')) fail('OAUTH_CONFIG_INVALID');
+  const binding = {issuer: auth.issuer, resource: auth.resource, clientId: auth.clientId};
+  const store = credentialStore ?? createOAuthCredentialStore();
+  async function currentToken() {
+    try {
+      await store.read(auth.credentialRef, binding);
+      return await store.withCredential(auth.credentialRef, binding, async record => {
+        if (record.tokens.expiresAt > now() + 30000) return {value: record.tokens.accessToken};
+        const plan = await discoverOAuth({origin, ...binding, scopes: record.tokens.scope.split(' '), fetchImpl, resolveHost});
+        const tokens = await refreshOAuthTokens({plan, tokens: record.tokens, fetchImpl, now});
+        return {tokens, value: tokens.accessToken};
+      });
+    } catch (error) {
+      if (error instanceof CloudError) throw error;
+      const code = typeof error?.code === 'string' && /^[A-Z][A-Z0-9_]{1,100}$/.test(error.code) ? error.code : 'OAUTH_CREDENTIAL_UNAVAILABLE';
+      throw new CloudError(code, 401, null, 'OAuth credentials could not be used. Reconnect through the configured issuer; do not repeat an unresolved write.');
+    }
+  }
+  async function perform(operation, {safeRead = false, all = false} = {}) {
+    for (let attempt = 1; attempt <= (safeRead ? 3 : 1); attempt++) {
+      const token = await currentToken();
+      let client;
+      try {
+        client = await createSdkClient({url: all ? `${origin}/mcp/all` : auth.resource, token, workspaceId, fetchImpl});
+        return await operation(client, token);
+      } catch (error) {
+        const status = Number.isInteger(error?.status) && error.status >= 400 && error.status <= 599 ? error.status : null;
+        const failure = error instanceof CloudError ? error : status !== null ? new CloudError(`HTTP_${status}`, status,
+          null, 'The cloud request was refused.', null, {retryAfter: error.retryAfter ?? null, requestId: error.requestId ?? null}) : new CloudError(
+          ['AbortError', 'TimeoutError'].includes(error?.name) ? 'CLOUD_TIMEOUT' : 'CLOUD_NETWORK_ERROR', 0,
+          {attempts: attempt}, safeRead ? 'The cloud read failed. Check the connection before retrying.'
+            : 'The cloud request did not return a conclusive result. Check its outcome before sending it again.');
+        const delay = safeRead && attempt < 3 ? retryDelay(failure, attempt, now) : null;
+        if (delay === null) throw failure;
+        await sleepImpl(delay);
+      } finally { await client?.close().catch(() => {}); }
+    }
+  }
+  const detailed = (name, args) => Object.hasOwn(SHAPES, name) ? {format: 'detailed', ...args} : args;
+  const scoped = (name, args) => detailed(name, {...args, ...(projectId ? {projectId} : {})});
+  const tool = (name, args, safeRead = false, path = null, method = 'GET') => perform(async (client, token) => {
+    const data = normalized(await client.callTool({name, arguments: args}, {timeout: 30000}), token);
+    if (!path) return data;
+    const parsed = restResponseContract(path, method).safeParse(data);
+    if (!parsed.success) fail('INVALID_RESPONSE', 502);
+    return parsed.data;
+  }, {safeRead});
+  return {
+    listCommands: () => perform(async (client, token) => {
+      const items = []; let cursor = '';
+      const visited = new Set([cursor]);
+      do {
+        // An explicit cursor selects the SDK's per-page path. A missing cursor
+        // auto-aggregates and can hide a repeated-page stop from our own guards.
+        const page = await client.listTools({cursor});
+        if (!Array.isArray(page?.tools)) fail('INVALID_RESPONSE', 502);
+        items.push(...page.tools);
+        if (items.length > 1000) fail('INVALID_RESPONSE', 502);
+        if (page.nextCursor === undefined) break;
+        if (typeof page.nextCursor !== 'string' || !page.nextCursor
+          || visited.has(page.nextCursor) || visited.size >= 100) fail('INVALID_RESPONSE', 502);
+        cursor = page.nextCursor; visited.add(cursor);
+      } while (true);
+      // Meta tools are registered only on the default view, not the flat listing.
+      const meta = await createSdkClient({url: auth.resource, token, workspaceId, fetchImpl});
+      try {
+        const described = new Map();
+        for (let start = 0; start < items.length; start += 10) {
+          const names = items.slice(start, start + 10).map(item => item.name);
+          if (names.some(name => typeof name !== 'string' || !name || name.length > 64)) fail('INVALID_RESPONSE', 502);
+          const data = normalized(await meta.callTool({name: 'describe_tools',
+            arguments: {names, include: 'input+output'}}, {timeout: 30000}), token);
+          if (!Array.isArray(data.tools) || data.tools.length !== names.length || data.unknown?.length) fail('INVALID_RESPONSE', 502);
+          for (const item of data.tools) {
+            if (!names.includes(item.name) || described.has(item.name)) fail('INVALID_RESPONSE', 502);
+            described.set(item.name, item);
+          }
+        }
+        return {items: items.map(item => ({...item, ...described.get(item.name), annotations: item.annotations}))};
+      } finally { await meta.close().catch(() => {}); }
+    }, {safeRead: true, all: true}),
+    describeCommand: name => perform(async (client, token) => {
+      const data = normalized(await client.callTool({name: 'describe_tools', arguments: {names: [name], include: 'input+output'}}, {timeout: 30000}), token);
+      if (!Array.isArray(data?.tools) || data.tools.length !== 1) fail('INVALID_RESPONSE', 502);
+      return data.tools[0];
+    }, {safeRead: true}),
+    callCommand: (name, args = {}) => tool(name, detailed(name, args)),
+    getWorkspace: () => tool('get_workspace', {}, true, '/v1/workspace'),
+    getProject: id => tool('get_project', {projectId: id}, true, '/v1/projects/' + encodeURIComponent(id)),
+    importWatches: (id, watches) => tool('import_link_watches', {projectId: id, watches}, false, '/v1/watches/import', 'POST'),
+    updateWatch: (watchId, patch) => tool('update_link_watch', {...patch, watchId}, false, '/v1/watches/' + encodeURIComponent(watchId), 'PATCH'),
+    listWatches: query => tool('list_link_watches', scoped('list_link_watches', query), true, '/v1/watches'),
+    listEvents: query => tool('list_events', {...scoped('list_events', query), feed: 'links'}, true, '/v1/events'),
+    listTargets: query => tool('list_targets', scoped('list_targets', query), true, '/v1/targets'),
+    listTargetEvents: query => tool('list_events', {...scoped('list_events', query), feed: 'targets'}, true, '/v1/target-events'),
+    exportWatches: query => tool('export_link_watches', scoped('export_link_watches', query), true, '/v1/exports/watches'),
+  };
+}

package/cli/native-lock.js

@@ -0,0 +1,22 @@
+// Only the OS advisory lock coordinates recovery. Path age is never ownership.
+import { ConfigError } from './config.js';
+let binding;
+export async function nativeLock(platform = process.platform) {
+  if (!['darwin', 'linux'].includes(platform)) throw new ConfigError('Sync lock recovery is unsupported on this platform; no writer started.');
+  if (!binding) {
+    try {
+      const { default: koffi } = await import('koffi');
+      const lib = koffi.load(platform === 'darwin' ? '/usr/lib/libSystem.B.dylib' : 'libc.so.6');
+      const flock = lib.func('int flock(int fd, int operation)');
+      binding = { acquire(fd) {
+        if (flock(fd, 2 | 4) === 0) return true;
+        const code = koffi.errno();
+        if (code === koffi.os.errno.EWOULDBLOCK || code === koffi.os.errno.EAGAIN) return false;
+        throw new ConfigError('Kernel sync lock failed; no writer started.');
+      } };
+    } catch (error) {
+      throw new ConfigError('Native sync lock is unavailable; reinstall the CLI with its platform dependencies. No writer started.');
+    }
+  }
+  return binding;
+}

package/cli/oauth-credentials.js

@@ -0,0 +1,196 @@
+import * as fs from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {homedir} from 'node:os';
+import {isAbsolute, join, parse, resolve} from 'node:path';
+import {randomBytes} from 'node:crypto';
+
+const MAX_BYTES = 300000;
+const fail = code => { throw Object.assign(new Error(code), {code}); };
+const exact = (value, keys) => value && typeof value === 'object' && !Array.isArray(value)
+  && Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+function bindingOf(value) {
+  if (!exact(value, ['issuer', 'resource', 'clientId'])) fail('OAUTH_CREDENTIAL_BINDING_INVALID');
+  for (const key of ['issuer', 'resource']) {
+    let url; try { url = new URL(value[key]); } catch { fail('OAUTH_CREDENTIAL_BINDING_INVALID'); }
+    if (typeof value[key] !== 'string' || value[key].length > 4096 || url.protocol !== 'https:'
+      || url.username || url.password || url.search || url.hash
+      || (key === 'issuer' ? url.origin !== value[key] : url.href !== value[key] || url.pathname !== '/mcp'))
+      fail('OAUTH_CREDENTIAL_BINDING_INVALID');
+  }
+  if (typeof value.clientId !== 'string' || !value.clientId || value.clientId.length > 2048
+    || /[\s\x00-\x1f\x7f]/.test(value.clientId)) fail('OAUTH_CREDENTIAL_BINDING_INVALID');
+  return {...value};
+}
+function tokensOf(value) {
+  if (!exact(value, ['accessToken', 'refreshToken', 'expiresAt', 'scope'])) fail('OAUTH_CREDENTIAL_TOKENS_INVALID');
+  for (const key of ['accessToken', 'refreshToken']) if (typeof value[key] !== 'string' || !value[key]
+    || Buffer.byteLength(value[key]) > 65536 || /[\x00-\x20\x7f]/.test(value[key])) fail('OAUTH_CREDENTIAL_TOKENS_INVALID');
+  if (!Number.isSafeInteger(value.expiresAt) || value.expiresAt <= 0 || typeof value.scope !== 'string'
+    || !value.scope || Buffer.byteLength(value.scope) > 4096 || !/^[A-Za-z0-9:._/-]+(?: [A-Za-z0-9:._/-]+)*$/.test(value.scope))
+    fail('OAUTH_CREDENTIAL_TOKENS_INVALID');
+  return {...value};
+}
+const reference = ref => { if (typeof ref !== 'string' || !/^oauth_[a-f0-9]{32}$/.test(ref)) fail('OAUTH_CREDENTIAL_REF_INVALID'); return ref; };
+const sameIdentity = (a, b) => a.dev === b.dev && a.ino === b.ino;
+const sameBinding = (a, b) => ['issuer', 'resource', 'clientId'].every(key => a[key] === b[key]);
+const sleep = ms => new Promise(done => setTimeout(done, ms));
+
+export function createOAuthCredentialStore({home = homedir(), platform = process.platform, now = Date.now, lockTimeoutMs = 2000} = {}) {
+  if (typeof home !== 'string' || !isAbsolute(home) || home.includes('\0')) fail('OAUTH_CREDENTIAL_HOME_INVALID');
+  if (!Number.isInteger(lockTimeoutMs) || lockTimeoutMs < 0 || lockTimeoutMs > 10000) fail('OAUTH_CREDENTIAL_LOCK_BOUND_INVALID');
+  const root = resolve(home), directory = join(root, '.agentlinkops', 'oauth');
+  const uid = process.getuid?.();
+  const privateStat = (info, mode) => info.uid === uid && (info.mode & 0o7777) === mode;
+  async function directories() {
+    // Darwin ACLs can grant access independently of these POSIX mode checks.
+    // Other platforms require separately verified native credential custody.
+    if (platform !== 'linux' || uid === undefined) fail('OAUTH_CREDENTIAL_STORAGE_UNSUPPORTED');
+    let path = parse(root).root;
+    for (const part of root.slice(path.length).split('/').filter(Boolean)) {
+      path = join(path, part);
+      const info = await fs.lstat(path);
+      if (!info.isDirectory()) fail('OAUTH_CREDENTIAL_PRIVATE_STORAGE_REQUIRED');
+    }
+    const homeInfo = await fs.lstat(root);
+    if (homeInfo.uid !== uid) fail('OAUTH_CREDENTIAL_PRIVATE_STORAGE_REQUIRED');
+    for (const path of [join(root, '.agentlinkops'), directory]) {
+      try { await fs.mkdir(path, {mode: 0o700}); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+      const info = await fs.lstat(path);
+      if (!info.isDirectory() || !privateStat(info, 0o700)) fail('OAUTH_CREDENTIAL_PRIVATE_STORAGE_REQUIRED');
+    }
+    return fs.lstat(directory);
+  }
+  async function unchangedDirectory(original) {
+    if (!sameIdentity(original, await directories())) fail('OAUTH_CREDENTIAL_STORAGE_CHANGED');
+  }
+  async function syncDirectory() {
+    const parent = await fs.open(directory, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try { await parent.sync(); } finally { await parent.close(); }
+  }
+  async function bytes(path, missing = false) {
+    let handle;
+    try {
+      const info = await fs.lstat(path);
+      if (!info.isFile() || info.nlink !== 1 || !privateStat(info, 0o600)) fail('OAUTH_CREDENTIAL_PRIVATE_STORAGE_REQUIRED');
+      handle = await fs.open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+      const actual = await handle.stat();
+      if (!sameIdentity(info, actual) || !actual.isFile() || actual.nlink !== 1 || !privateStat(actual, 0o600)) fail('OAUTH_CREDENTIAL_STORAGE_CHANGED');
+      if (actual.size > MAX_BYTES) fail('OAUTH_CREDENTIAL_RECORD_INVALID');
+      const buffer = Buffer.alloc(MAX_BYTES + 1);
+      let offset = 0;
+      while (offset < buffer.length) {
+        const read = await handle.read(buffer, offset, buffer.length - offset, offset);
+        if (!read.bytesRead) break;
+        offset += read.bytesRead;
+      }
+      if (offset > MAX_BYTES) fail('OAUTH_CREDENTIAL_RECORD_INVALID');
+      return buffer.subarray(0, offset).toString('utf8');
+    } catch (error) { if (missing && error.code === 'ENOENT') return null; throw error; }
+    finally { await handle?.close(); }
+  }
+  function recordOf(text, binding) {
+    let record; try { record = JSON.parse(text); } catch { fail('OAUTH_CREDENTIAL_RECORD_INVALID'); }
+    if (!exact(record, ['version', 'revision', 'binding', 'tokens']) || record.version !== 1
+      || !Number.isSafeInteger(record.revision) || record.revision < 1) fail('OAUTH_CREDENTIAL_RECORD_INVALID');
+    const stored = bindingOf(record.binding), tokens = tokensOf(record.tokens);
+    if (!sameBinding(stored, binding)) fail('OAUTH_CREDENTIAL_BINDING_MISMATCH');
+    return {version: 1, revision: record.revision, binding: stored, tokens};
+  }
+  async function atomic(ref, record, before, original) {
+    const path = join(directory, ref + '.json'), temporary = join(directory, '.' + ref + '.' + randomBytes(16).toString('hex') + '.tmp');
+    let handle, owned = false;
+    try {
+      const text = JSON.stringify(record);
+      if (Buffer.byteLength(text) > MAX_BYTES) fail('OAUTH_CREDENTIAL_RECORD_INVALID');
+      handle = await fs.open(temporary, 'wx', 0o600); owned = true;
+      if (!privateStat(await handle.stat(), 0o600)) fail('OAUTH_CREDENTIAL_PRIVATE_STORAGE_REQUIRED');
+      await handle.writeFile(text); await handle.sync(); await handle.close(); handle = undefined;
+      await unchangedDirectory(original);
+      if (await bytes(path, true) !== before) fail('OAUTH_CREDENTIAL_STORAGE_CHANGED');
+      if (before === null) { await fs.link(temporary, path); await fs.unlink(temporary); }
+      else await fs.rename(temporary, path);
+      owned = false;
+      await syncDirectory();
+    } finally { await handle?.close(); if (owned) await fs.unlink(temporary).catch(() => {}); }
+  }
+  async function locked(ref, work) {
+    const original = await directories(), path = join(directory, ref + '.lock'), nonce = randomBytes(16).toString('hex');
+    const deadline = Date.now() + lockTimeoutMs;
+    let lock;
+    while (!lock) {
+      try { lock = await fs.open(path, 'wx', 0o600); }
+      catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        if (Date.now() >= deadline) fail('OAUTH_CREDENTIAL_LOCKED');
+        await sleep(20);
+      }
+    }
+    let identity, initialized = false;
+    try {
+      identity = await lock.stat();
+      if (!privateStat(identity, 0o600)) fail('OAUTH_CREDENTIAL_PRIVATE_STORAGE_REQUIRED');
+      await lock.writeFile(nonce); await lock.sync();
+      initialized = true;
+      return await work(original);
+    } finally {
+      try {
+        // Before initialization, the open inode proves ownership even if the nonce write failed.
+        identity ??= await lock.stat().catch(() => null);
+        const current = await fs.lstat(path).catch(() => null);
+        if (identity && current && sameIdentity(identity, current)
+          && (!initialized || await bytes(path) === nonce)) await fs.unlink(path);
+      } finally { await lock.close(); }
+    }
+  }
+  async function safe(work) {
+    try { return await work(); }
+    catch (error) { if (typeof error.code === 'string' && error.code.startsWith('OAUTH_CREDENTIAL_')) throw error; fail('OAUTH_CREDENTIAL_STORAGE_FAILED'); }
+  }
+  return {
+    async checkAvailability() { return safe(async () => { await directories(); }); },
+    async create(binding, tokens) {
+      binding = bindingOf(binding); tokens = tokensOf(tokens);
+      return safe(async () => {
+        const ref = 'oauth_' + randomBytes(16).toString('hex');
+        await locked(ref, original => atomic(ref, {version: 1, revision: 1, binding, tokens}, null, original));
+        return ref;
+      });
+    },
+    async read(ref, binding) {
+      reference(ref); binding = bindingOf(binding);
+      return safe(async () => { const original = await directories(); const text = await bytes(join(directory, ref + '.json'), true);
+        if (text === null) fail('OAUTH_CREDENTIAL_NOT_FOUND');
+        const record = recordOf(text, binding); await unchangedDirectory(original); return record; });
+    },
+    async withCredential(ref, binding, callback) {
+      reference(ref); binding = bindingOf(binding);
+      if (typeof callback !== 'function') fail('OAUTH_CREDENTIAL_CALLBACK_INVALID');
+      let callbackError, callbackFailed = false;
+      try { return await safe(() => locked(ref, async original => {
+        const path = join(directory, ref + '.json'), before = await bytes(path, true);
+        if (before === null) fail('OAUTH_CREDENTIAL_NOT_FOUND');
+        const record = recordOf(before, binding);
+        let result; try { result = await callback(structuredClone(record)); } catch (error) { callbackFailed = true; callbackError = error; throw error; }
+        if (!result || typeof result !== 'object' || !Object.hasOwn(result, 'value')
+          || Object.keys(result).some(key => !['tokens', 'value'].includes(key))) fail('OAUTH_CREDENTIAL_CALLBACK_INVALID');
+        await unchangedDirectory(original);
+        if (await bytes(path) !== before) fail('OAUTH_CREDENTIAL_STORAGE_CHANGED');
+        if (result.tokens !== undefined) {
+          if (record.revision === Number.MAX_SAFE_INTEGER) fail('OAUTH_CREDENTIAL_RECORD_INVALID');
+          await atomic(ref, {...record, revision: record.revision + 1, tokens: tokensOf(result.tokens)}, before, original);
+        }
+        return result.value;
+      })); } catch (error) { if (callbackFailed) throw callbackError; throw error; }
+    },
+    async remove(ref, binding) {
+      reference(ref); binding = bindingOf(binding);
+      return safe(() => locked(ref, async original => {
+        const path = join(directory, ref + '.json'), before = await bytes(path, true);
+        if (before === null) return false;
+        recordOf(before, binding); await unchangedDirectory(original);
+        if (await bytes(path) !== before) fail('OAUTH_CREDENTIAL_STORAGE_CHANGED');
+        await fs.unlink(path); await syncDirectory(); return true;
+      }));
+    },
+  };
+}