agentlinkops 0.6.8 → 0.6.10

package/cli/oauth-flow.js

@@ -0,0 +1,259 @@
+import {createServer} from 'node:http';
+import {createHash, randomBytes, timingSafeEqual} from 'node:crypto';
+import {lookup} from 'node:dns/promises';
+import ipaddr from 'ipaddr.js';
+import {validatePublicUrl} from '../src/verifier/url.js';
+
+const plans = new WeakSet();
+const resolvers = new WeakMap();
+const authorizations = new WeakMap();
+const LIMIT = 1024 * 1024;
+const fail = code => { throw Object.assign(new Error(code), {code}); };
+const check = (value, code) => { if (!value) fail(code); };
+const same = (a, b) => typeof a === 'string' && typeof b === 'string'
+  && Buffer.byteLength(a) === Buffer.byteLength(b) && timingSafeEqual(Buffer.from(a), Buffer.from(b));
+const secret = value => typeof value === 'string' && value.length > 0 && value.length <= 65536 && !/[\s\u0000-\u001f\u007f]/.test(value);
+const normalizeScopes = value => {
+  check(Array.isArray(value) && value.length > 0 && value.length <= 100
+    && value.every(s => typeof s === 'string' && /^[\x21\x23-\x5b\x5d-\x7e]{1,200}$/.test(s))
+    && new Set(value).size === value.length, 'INVALID_OAUTH_SCOPES');
+  return [...value].sort();
+};
+const scopeString = value => {
+  check(typeof value === 'string' && value.length <= 20000 && value.trim() === value
+    && !value.includes('  '), 'TOKEN_SCOPE_MISMATCH');
+  try { return normalizeScopes(value.split(' ')); } catch { fail('TOKEN_SCOPE_MISMATCH'); }
+};
+const sameScopes = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function publicHttps(value, code) {
+  check(typeof value === 'string' && validatePublicUrl(value).valid, code);
+  let url; try { url = new URL(value); } catch { fail(code); }
+  check(url.protocol === 'https:' && !url.hash && !url.username && !url.password, code);
+  return url;
+}
+function originOf(value) {
+  const url = publicHttps(value, 'CANONICAL_HTTPS_ORIGIN_REQUIRED');
+  check(value === url.origin, 'CANONICAL_HTTPS_ORIGIN_REQUIRED');
+  return url.origin;
+}
+function endpoint(value, issuer) {
+  const url = publicHttps(value, 'ISSUER_ENDPOINT_INVALID');
+  check(url.origin === issuer && value === url.href && !value.includes('?') && !value.includes('#'), 'ISSUER_ENDPOINT_INVALID');
+  return url.href;
+}
+function requirePlan(plan) {
+  check(plan && plans.has(plan), 'OAUTH_PLAN_REQUIRED');
+  return plan;
+}
+function requested(plan, scopes) {
+  const value = normalizeScopes(scopes);
+  check(value.includes('offline_access') && value.every(s => plan.scopes.includes(s)), 'INVALID_OAUTH_SCOPES');
+  return value;
+}
+
+const defaultResolver = hostname => lookup(hostname, {all: true});
+async function publicDestination(url, resolveHost) {
+  check(typeof resolveHost === 'function', 'OAUTH_DESTINATION_REFUSED');
+  let timer;
+  try {
+    // This is DNS preflight, not address pinning or a rebinding-proof transport.
+    const addresses = await Promise.race([Promise.resolve().then(() => resolveHost(new URL(url).hostname)),
+      new Promise((_, reject) => { timer = setTimeout(() => reject(new Error()), 20000); })]);
+    check(Array.isArray(addresses) && addresses.length > 0 && addresses.length <= 100
+      && addresses.every(value => {
+        try { return ipaddr.process(typeof value === 'string' ? value : value?.address).range() === 'unicast'; }
+        catch { return false; }
+      }), 'OAUTH_DESTINATION_REFUSED');
+  } catch { fail('OAUTH_DESTINATION_REFUSED'); }
+  finally { clearTimeout(timer); }
+}
+async function jsonRequest(fetchImpl, url, init = {}, resolveHost = defaultResolver) {
+  await publicDestination(url, resolveHost);
+  let response;
+  try { response = await fetchImpl(url, {...init, redirect: 'error', signal: AbortSignal.timeout(20000)}); }
+  catch { fail('OAUTH_REQUEST_FAILED'); }
+  check(response && !response.redirected && !(response.status >= 300 && response.status < 400)
+    && (!response.url || response.url === url), 'OAUTH_REDIRECT_REFUSED');
+  check(response.headers?.get('content-type')?.split(';')[0].trim().toLowerCase() === 'application/json', 'JSON_RESPONSE_REQUIRED');
+  const length = response.headers.get('content-length');
+  if (length !== null) check(/^\d+$/.test(length) && Number(length) <= LIMIT, 'RESPONSE_TOO_LARGE');
+  check(response.body?.getReader, 'JSON_RESPONSE_REQUIRED');
+  const reader = response.body.getReader(), chunks = [];
+  let bytes = 0;
+  try {
+    while (true) {
+      const {done, value} = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
+      if (bytes > LIMIT) { await reader.cancel().catch(() => {}); fail('RESPONSE_TOO_LARGE'); }
+      chunks.push(Buffer.from(value));
+    }
+  } catch (error) {
+    if (error?.code === 'RESPONSE_TOO_LARGE') throw error;
+    fail('OAUTH_RESPONSE_FAILED');
+  } finally { reader.releaseLock(); }
+  let data;
+  try { data = JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(Buffer.concat(chunks, bytes))); }
+  catch { fail('JSON_RESPONSE_REQUIRED'); }
+  check(data && typeof data === 'object' && !Array.isArray(data), 'JSON_RESPONSE_REQUIRED');
+  return {response, data};
+}
+
+export async function discoverOAuth({origin, issuer, clientId, scopes, fetchImpl = fetch, resolveHost = defaultResolver}) {
+  originOf(origin); originOf(issuer);
+  check(typeof clientId === 'string' && clientId.length > 0 && clientId.length <= 2048
+    && !/[\s\u0000-\u001f\u007f]/.test(clientId), 'EXISTING_PUBLIC_CLIENT_REQUIRED');
+  const declared = normalizeScopes(scopes);
+  check(declared.includes('offline_access'), 'INVALID_OAUTH_SCOPES');
+  const resource = `${origin}/mcp`;
+  const protectedResource = await jsonRequest(fetchImpl, `${origin}/.well-known/oauth-protected-resource/mcp`, {}, resolveHost);
+  const p = protectedResource.data;
+  check(protectedResource.response.ok && p.resource === resource
+    && Array.isArray(p.authorization_servers) && p.authorization_servers.length === 1
+    && p.authorization_servers[0] === issuer, 'RESOURCE_DISCOVERY_MISMATCH');
+  check(Array.isArray(p.scopes_supported) && declared.filter(s => s !== 'offline_access')
+    .every(s => p.scopes_supported.includes(s)), 'RESOURCE_SCOPES_MISSING');
+  const discovery = await jsonRequest(fetchImpl, `${issuer}/.well-known/oauth-authorization-server`, {}, resolveHost);
+  const m = discovery.data;
+  check(discovery.response.ok && m.issuer === issuer, 'ISSUER_DISCOVERY_MISMATCH');
+  check(Array.isArray(m.code_challenge_methods_supported) && m.code_challenge_methods_supported.includes('S256'), 'PKCE_DISCOVERY_FAILED');
+  check(Array.isArray(m.grant_types_supported) && ['authorization_code', 'refresh_token']
+    .every(g => m.grant_types_supported.includes(g)), 'GRANT_DISCOVERY_FAILED');
+  if (m.response_types_supported !== undefined)
+    check(Array.isArray(m.response_types_supported) && m.response_types_supported.includes('code'), 'GRANT_DISCOVERY_FAILED');
+  if (m.token_endpoint_auth_methods_supported !== undefined)
+    check(Array.isArray(m.token_endpoint_auth_methods_supported) && m.token_endpoint_auth_methods_supported.includes('none'), 'EXISTING_PUBLIC_CLIENT_REQUIRED');
+  if (m.scopes_supported !== undefined)
+    check(Array.isArray(m.scopes_supported) && declared.every(s => m.scopes_supported.includes(s)), 'RESOURCE_SCOPES_MISSING');
+  const plan = Object.freeze({origin, issuer, clientId, resource, scopes: Object.freeze(declared),
+    authorizationEndpoint: endpoint(m.authorization_endpoint, issuer), tokenEndpoint: endpoint(m.token_endpoint, issuer),
+    ...(m.revocation_endpoint === undefined ? {} : {revocationEndpoint: endpoint(m.revocation_endpoint, issuer)}),
+    requireIssuerResponse: m.authorization_response_iss_parameter_supported === true});
+  plans.add(plan);
+  resolvers.set(plan, resolveHost);
+  return plan;
+}
+
+export async function receiveOAuthConsent({plan, scopes, timeoutMs = 600000, onAuthorization}) {
+  requirePlan(plan);
+  const selected = requested(plan, scopes);
+  check(Number.isInteger(timeoutMs) && timeoutMs >= 1 && timeoutMs <= 600000 && typeof onAuthorization === 'function', 'INVALID_OAUTH_CONSENT');
+  await publicDestination(plan.authorizationEndpoint, resolvers.get(plan));
+  const verifier = randomBytes(64).toString('base64url'), state = randomBytes(32).toString('base64url');
+  let finish, rejectCallback, rejectTimeout, used = false, timer;
+  const received = new Promise((resolve, reject) => { finish = resolve; rejectCallback = reject; });
+  received.catch(() => {});
+  const timedOut = new Promise((_, reject) => { rejectTimeout = reject; });
+  timedOut.catch(() => {});
+  const headers = {'Cache-Control': 'no-store', 'Referrer-Policy': 'no-referrer', 'Content-Type': 'text/plain',
+    'Content-Security-Policy': "default-src 'none'; frame-ancestors 'none'"};
+  const server = createServer({maxHeaderSize: 16384}, (request, response) => {
+    if (typeof request.url !== 'string' || request.url.length > 8192) {
+      response.writeHead(400, headers); response.end('Invalid authorization response.'); return;
+    }
+    let url; try { url = new URL(request.url, 'http://127.0.0.1'); }
+    catch { response.writeHead(400, headers); response.end('Invalid authorization response.'); return; }
+    if (request.method === 'GET' && url.pathname === '/oauth/complete') {
+      response.writeHead(200, headers); response.end('Authorization received. You can close this tab.'); return;
+    }
+    if (request.method !== 'GET' || url.pathname !== '/oauth/callback' || request.socket.remoteAddress !== '127.0.0.1'
+      || !request.url.startsWith('/') || request.url.startsWith('//')
+      || request.headers.host !== `127.0.0.1:${server.address().port}` || used) {
+      response.writeHead(404, headers); response.end('Not found.'); return;
+    }
+    const params = url.searchParams;
+    const duplicate = ['code', 'state', 'iss', 'error'].some(k => params.getAll(k).length > 1);
+    if (duplicate || !same(params.get('state'), state) || (params.has('iss') && params.get('iss') !== plan.issuer)
+      || (plan.requireIssuerResponse && !params.has('iss')) || (params.has('code') && params.has('error'))) {
+      response.writeHead(400, headers); response.end('Invalid authorization response.'); return;
+    }
+    used = true;
+    response.writeHead(303, {...headers, Location: '/oauth/complete'}); response.end();
+    if (params.has('error')) rejectCallback(Object.assign(new Error('CONSENT_DENIED'), {code: 'CONSENT_DENIED'}));
+    else if (!secret(params.get('code'))) rejectCallback(Object.assign(new Error('AUTHORIZATION_CODE_MISSING'), {code: 'AUTHORIZATION_CODE_MISSING'}));
+    else finish(params.get('code'));
+  });
+  server.requestTimeout = 20000; server.headersTimeout = 10000;
+  try {
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+    const redirectUri = `http://127.0.0.1:${server.address().port}/oauth/callback`;
+    const url = new URL(plan.authorizationEndpoint);
+    for (const [key, value] of Object.entries({response_type: 'code', client_id: plan.clientId, redirect_uri: redirectUri,
+      scope: selected.join(' '), resource: plan.resource, state, code_challenge: createHash('sha256').update(verifier).digest('base64url'),
+      code_challenge_method: 'S256'})) url.searchParams.set(key, value);
+    timer = setTimeout(() => rejectTimeout(Object.assign(new Error('CONSENT_PENDING'), {code: 'CONSENT_PENDING'})), timeoutMs);
+    // Race the browser hook too: a stalled opener must not retain the listener forever.
+    await Promise.race([Promise.resolve().then(() => onAuthorization({authorizationUrl: url.href, redirectUri,
+      clientId: plan.clientId, scopes: [...selected]})), timedOut]);
+    const authorization = Object.freeze({code: await Promise.race([received, timedOut]), verifier, redirectUri});
+    authorizations.set(authorization, {plan, scopes: selected, used: false});
+    return authorization;
+  } catch (error) {
+    if (['CONSENT_DENIED', 'AUTHORIZATION_CODE_MISSING', 'CONSENT_PENDING'].includes(error?.code)) fail(error.code);
+    fail('OAUTH_CONSENT_FAILED');
+  } finally {
+    clearTimeout(timer);
+    server.closeAllConnections();
+    await new Promise(done => server.close(done));
+  }
+}
+
+function retainTokens(plan, data, selected, now, previous) {
+  const at = typeof now === 'function' ? now() : now;
+  check(Number.isSafeInteger(at) && at >= 0, 'INVALID_OAUTH_CLOCK');
+  check(secret(data.access_token) && typeof data.token_type === 'string' && data.token_type.toLowerCase() === 'bearer'
+    && Number.isSafeInteger(data.expires_in) && data.expires_in > 0 && data.expires_in <= 31536000, 'TOKEN_CONTRACT_MISMATCH');
+  check((data.resource === undefined || data.resource === plan.resource)
+    && (data.iss === undefined || data.iss === plan.issuer), 'TOKEN_RESOURCE_MISMATCH');
+  const granted = data.scope === undefined ? selected : scopeString(data.scope);
+  check(sameScopes(granted, selected), 'TOKEN_SCOPE_MISMATCH');
+  const refreshToken = data.refresh_token === undefined ? previous?.refreshToken : data.refresh_token;
+  check(secret(refreshToken), 'REFRESH_TOKEN_REQUIRED');
+  let expiresAt = at + data.expires_in * 1000;
+  check(Number.isSafeInteger(expiresAt), 'TOKEN_CONTRACT_MISMATCH');
+  if (data.access_token.split('.').length === 3) {
+    let header, claims;
+    try {
+      const [h, p, signature] = data.access_token.split('.');
+      check([h, p, signature].every(s => /^[A-Za-z0-9_-]+$/.test(s)), 'TOKEN_CLAIMS_INVALID');
+      header = JSON.parse(Buffer.from(h, 'base64url').toString('utf8'));
+      claims = JSON.parse(Buffer.from(p, 'base64url').toString('utf8'));
+    } catch { fail('TOKEN_CLAIMS_INVALID'); }
+    // Binding checks only. The resource server verifies the signature and current grant.
+    check(typeof header?.alg === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(header.alg)
+      && header.alg.toLowerCase() !== 'none' && claims?.iss === plan.issuer
+      && (claims.aud === plan.resource || (Array.isArray(claims.aud) && claims.aud.length === 1 && claims.aud[0] === plan.resource))
+      && Number.isSafeInteger(claims.exp) && claims.exp * 1000 > at
+      && (claims.nbf === undefined || (Number.isSafeInteger(claims.nbf) && claims.nbf * 1000 <= at))
+      && (claims.client_id === undefined || claims.client_id === plan.clientId)
+      && (claims.azp === undefined || claims.azp === plan.clientId), 'TOKEN_CLAIMS_INVALID');
+    if (claims.scope !== undefined) check(sameScopes(scopeString(claims.scope), selected), 'TOKEN_SCOPE_MISMATCH');
+    expiresAt = Math.min(expiresAt, claims.exp * 1000);
+  }
+  return {accessToken: data.access_token, refreshToken, expiresAt, scope: granted.join(' ')};
+}
+
+export async function exchangeOAuthCode({plan, authorization, scopes, fetchImpl = fetch, now = Date.now}) {
+  requirePlan(plan);
+  const selected = requested(plan, scopes), bound = authorizations.get(authorization);
+  check(bound?.plan === plan && !bound.used && sameScopes(bound.scopes, selected), 'OAUTH_AUTHORIZATION_REQUIRED');
+  bound.used = true;
+  const {response, data} = await jsonRequest(fetchImpl, plan.tokenEndpoint, {method: 'POST',
+    headers: {'Content-Type': 'application/x-www-form-urlencoded'}, body: new URLSearchParams({client_id: plan.clientId,
+      grant_type: 'authorization_code', code: authorization.code, code_verifier: authorization.verifier,
+      redirect_uri: authorization.redirectUri, resource: plan.resource})}, resolvers.get(plan));
+  check(response.ok, 'CODE_EXCHANGE_FAILED');
+  return retainTokens(plan, data, selected, now);
+}
+
+export async function refreshOAuthTokens({plan, tokens, fetchImpl = fetch, now = Date.now}) {
+  requirePlan(plan);
+  check(tokens && secret(tokens.refreshToken), 'REFRESH_TOKEN_REQUIRED');
+  const selected = requested(plan, scopeString(tokens.scope));
+  const {response, data} = await jsonRequest(fetchImpl, plan.tokenEndpoint, {method: 'POST',
+    headers: {'Content-Type': 'application/x-www-form-urlencoded'}, body: new URLSearchParams({client_id: plan.clientId,
+      grant_type: 'refresh_token', refresh_token: tokens.refreshToken, scope: selected.join(' '), resource: plan.resource})}, resolvers.get(plan));
+  check(response.ok, 'REFRESH_FAILED');
+  // RFC6749 section6 permits omission of a replacement refresh token.
+  return retainTokens(plan, data, selected, now, tokens);
+}

package/cli/setup-plan.js

@@ -147,18 +147,18 @@ function taskSteps(goal, mode, inspection, unsafe) {
         : 'Gather customer-supplied site, audience, source and asset context before drafting.',
       ['Site and audience context', 'Source and claims rules'], ['A bounded content brief with verified source requirements and an existing content owner']));
     steps.push(step('prepare-cited-content', 'customer_agent',
-      'Use the site’s content router when present, then source-cited-content-builder, source-cited-humanizer, content-defingerprinting, internal-linking-optimizer, applicable image workflow and pre-publish-review. An authored result has no AgentLinkOps account prerequisite.',
-      ['Approved task scope', 'Applicable content skills and primary-source evidence'], ['Cited content artifact and recorded review gates; draft, reviewed and published states remain distinct']));
+      'Follow the customer’s existing content, source and review process with their chosen tools. Use packaged recipes only when explicitly selected; installed skills do not select a method or replace customer instructions. Keep unsupported claims and incomplete reviews unresolved. Record actual review outcomes, and verify the public result only after separately authorized publication. An authored result has no AgentLinkOps account prerequisite.',
+      ['Authorized task scope', 'Customer-selected content process, source requirements and review policy'], ['Content artifact with supporting evidence and actual review outcomes; draft, reviewed and published states remain distinct, and publication requires public readback']));
   } else {
     steps.push(step('qualify-campaign-inputs', 'customer_agent',
       'Inspect customer-selected records and assets; qualify exact source pages and claim-specific evidence. Preserve unknowns and duplicate references. An optional SQLite CRM is not required.',
       ['Customer-selected records', 'A relevant asset and campaign objective'], ['Qualified opportunities with exact source pages, evidence, duplicate accounting and unresolved claims']));
     steps.push(step('prepare-campaign-handoff', 'customer_agent',
-      'Prepare an external-tool draft and reviewed mapping. Keep the customer’s CRM or sender responsible for contacts, suppression, reply stops and delivery; apply required content gates to authored copy.',
-      ['Qualified opportunities', 'Chosen external tool and its supported fields'], ['Draft handoff with campaign references and supported external IDs; no sending or connection is implied']));
+      'Prepare an external-tool draft and reviewed mapping using the customer’s source, editorial and review policy. Keep the customer’s CRM or sender responsible for contacts, suppression, reply stops and delivery. Packaged recipes are optional guidance only when explicitly selected and cannot override customer policy or authorize sending.',
+      ['Qualified opportunities', 'Chosen external tool, supported fields and customer review policy'], ['Draft handoff with actual review outcomes, campaign references and supported external IDs; no sending or connection is implied']));
   }
   steps.push(step('record-resume-checkpoint', 'customer_agent',
-    'Prepare a checkpoint in the customer’s chosen record format for later approval to save. Preserve references, external IDs and completed evidence; read back before replaying an external action.',
+    'Prepare or save a checkpoint in the customer’s chosen record format within their existing authorization. Preserve references, external IDs and completed evidence; distinguish a prepared checkpoint from a saved checkpoint with readback, and read back before replaying an external action.',
     ['Chosen record ownership and format'], ['Resumable next action; draft, sent, replied and independently verified placement states remain separate']));
   return steps;
 }

package/cli/status.js

@@ -13,11 +13,23 @@ export function disagreements(entries, observations) {
   for (const entry of entries) {
     const row = latest.get(entry.id);
     if (!row) { out.push({ entry, kind: 'never_checked' }); continue; }
-    if (entry.intent === 'expected' && ['absent','confirmed_missing'].includes(row.state) && row.complete) out.push({ entry, row, kind: 'lost' });
+    if (entry.intent === 'expected') {
+      const hostedState = row.source === 'cloud' ? row.result?.watchState : null;
+      const confirmed = row.state === 'confirmed_missing'
+        || (row.state === 'absent' && hostedState === 'confirmed_missing');
+      const suspected = row.state === 'suspected_missing' || row.state === 'absent'
+        || (row.state === 'unknown' && hostedState === 'suspected_missing');
+      const missing = ['absent', 'suspected_missing', 'confirmed_missing'].includes(row.state);
+      // The change mirror omits repeated checks, so raw absence cannot prove confirmation.
+      if ((confirmed || suspected) && row.complete === true) {
+        out.push({ entry, row, kind: confirmed ? 'lost' : 'suspected_missing' });
+      } else if (missing || ['unknown', 'source_unavailable'].includes(row.state)) {
+        out.push({ entry, row, kind: 'cannot_say' });
+      }
+    }
     // Nothing is promoted automatically: whether a link that appeared is one we now EXPECT is
     // a judgement about a relationship, not about HTML. So this proposes the edit and stops.
     if (entry.intent === 'wanted' && row.state === 'present') out.push({ entry, row, kind: 'appeared', suggest: { intent: 'expected' } });
-    if (entry.intent === 'expected' && row.state === 'unknown') out.push({ entry, row, kind: 'cannot_say' });
   }
   return out;
 }

package/cli/sync-lock.js

@@ -0,0 +1,105 @@
+import { constants } from 'node:fs';
+import { open, lstat, realpath, readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { ConfigError } from './config.js';
+import { nativeLock } from './native-lock.js';
+const run = promisify(execFile);
+const MAX = 4096;
+const unknown = () => new ConfigError('Sync lock ownership is unknown; marker preserved. Confirm the original writer has stopped and recover from a copy of the ledger. Do not delete a live lock.');
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+async function markerText(handle) {
+  const buffer = Buffer.alloc(MAX + 1);
+  const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+  if (bytesRead > MAX) throw unknown();
+  return buffer.subarray(0, bytesRead).toString('utf8');
+}
+const validFile = s => s.isFile() && s.nlink === 1 && s.uid === process.getuid() && !(s.mode & 0o022);
+async function identity() {
+  if (process.platform === 'linux') return (await readFile('/proc/sys/kernel/random/boot_id', 'utf8')).trim();
+  if (process.platform === 'darwin') return (await run('/usr/sbin/sysctl', ['-n', 'kern.bootsessionuuid'], { timeout: 2000, maxBuffer: MAX })).stdout.trim();
+  throw unknown();
+}
+async function birth() {
+  if (process.platform === 'linux') {
+    const stat = await readFile(`/proc/${process.pid}/stat`, 'utf8');
+    return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+  }
+  return (await run('/bin/ps', ['-p', String(process.pid), '-o', 'lstart='], { timeout: 2000, maxBuffer: MAX })).stdout.trim();
+}
+// Unknown/reused live PIDs remain protected. ESRCH is the only reclaiming probe.
+function departed(pid) {
+  try { process.kill(pid, 0); return false; }
+  catch (error) { if (error.code === 'ESRCH') return true; throw unknown(); }
+}
+export async function acquireSyncLock(dir, command, { kernel = nativeLock, bootIdentity = identity, processBirth = birth, isDeparted = departed, afterMarkerCreated, markerName = 'sync.lock' } = {}) {
+  if (typeof markerName !== 'string' || !markerName || markerName.length > 255 || /[\/\\\x00]/.test(markerName) || ['.', '..'].includes(markerName)) throw unknown();
+  const osLock = await kernel(); // Unsupported/native failure precedes filesystem mutation.
+  let root;
+  try { root = await realpath(dir); }
+  catch (error) { if (error.code === 'ENOENT') throw new ConfigError('No ledger here; run agentlinkops init first.'); throw unknown(); }
+  const rootInfo = await lstat(root);
+  if (!rootInfo.isDirectory() || rootInfo.uid !== process.getuid() || rootInfo.mode & 0o022) throw unknown();
+  const path = join(root, markerName), gatePath = join(root, markerName === 'sync.lock' ? '.sync-gate' : `.${markerName}.gate`);
+  const ledgerIdentity = join(root, markerName);
+  let gate, marker, owned, acquired = false;
+  try {
+    gate = await open(gatePath, constants.O_RDWR | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    const gateInfo = await gate.stat();
+    if (!validFile(gateInfo) || !same(gateInfo, await lstat(gatePath))) throw unknown();
+    if (!osLock.acquire(gate.fd)) throw new ConfigError('Sync writer is active; wait for it to finish. No lock was changed.');
+    acquired = true;
+    const checkGate = async () => {
+      const currentGate = await lstat(gatePath), currentRoot = await lstat(root);
+      if (!same(gateInfo, currentGate) || !validFile(currentGate) || !same(rootInfo, currentRoot) || currentRoot.uid !== process.getuid() || currentRoot.mode & 0o022) throw unknown();
+    };
+    await checkGate();
+    const boot = await bootIdentity(), started = await processBirth();
+    if (!boot || !started || boot.length > 256 || started.length > 256) throw unknown();
+    try { marker = await open(path, constants.O_RDWR | constants.O_NOFOLLOW); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (marker) {
+      const info = await marker.stat();
+      if (!validFile(info) || info.size > MAX || !same(info, await lstat(path))) throw unknown();
+      let prior;
+      try { prior = JSON.parse(await markerText(marker)); } catch { throw unknown(); }
+      if (Object.keys(prior).sort().join(',') !== 'boot,command,host,ledger,nonce,pid,started,uid,version'
+        || prior.version !== 1 || prior.uid !== process.getuid() || prior.host !== hostname() || prior.boot !== boot
+        || prior.ledger !== ledgerIdentity || !Number.isSafeInteger(prior.pid) || prior.pid < 1
+        || typeof prior.started !== 'string' || !prior.started || prior.started.length > 256
+        || !/^[0-9a-f-]{36}$/.test(prior.nonce) || typeof prior.command !== 'string' || prior.command.length > 64) throw unknown();
+      if (!isDeparted(prior.pid)) throw new ConfigError('Sync marker names a live or reused process; marker preserved. Wait for the writer or inspect a ledger copy.');
+      await checkGate();
+      if (!same(info, await lstat(path))) throw unknown();
+      await marker.close(); marker = null;
+      await unlink(path);
+    }
+    await checkGate();
+    marker = await open(path, constants.O_RDWR | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    await afterMarkerCreated?.();
+    owned = { version: 1, nonce: randomUUID(), pid: process.pid, started, boot, uid: process.getuid(), host: hostname(), ledger: ledgerIdentity, command };
+    await marker.writeFile(JSON.stringify(owned) + '\n');
+    await marker.sync();
+    const markerInfo = await marker.stat();
+    await checkGate();
+    return { path, async release() {
+      try {
+        await checkGate();
+        const current = await lstat(path);
+        if (!same(markerInfo, current) || !validFile(current)) throw unknown();
+        const text = await markerText(marker);
+        if (text !== JSON.stringify(owned) + '\n') throw unknown();
+        await unlink(path);
+      } finally { await marker.close(); await gate.close(); }
+    } };
+  } catch (error) {
+    // Failed/partial marker initialization is deliberately preserved as unknown.
+    await marker?.close(); await gate?.close();
+    if (error instanceof ConfigError) throw error;
+    if (error.code === 'ENOENT' && !acquired) throw new ConfigError('No ledger here; run agentlinkops init first.');
+    throw unknown();
+  }
+}

package/cli/sync.js

@@ -93,7 +93,7 @@ export async function pullTargetEvents(client, state, options = {}) {
 }
 
 /** The shared walk. One cursor key per feed, and the key is the only thing that differs. */
-async function pullFeed(feed, cursorKey, state, { maxPages = 100, onSnapshot = null } = {}) {
+async function pullFeed(feed, cursorKey, state, { maxPages = 100, onSnapshot = null, recoverInvalidCursor = false } = {}) {
   const events = [], gaps = [];
   let cursor = state.cursors?.[cursorKey] ?? null;
   let pages = 0, resynced = false;
@@ -101,16 +101,20 @@ async function pullFeed(feed, cursorKey, state, { maxPages = 100, onSnapshot = n
     let page;
     try { page = await feed.list({ cursor, limit: 100 }); }
     catch (error) {
-      if (!(error instanceof CloudError) || error.code !== 'CURSOR_EXPIRED') throw error;
+      const invalidBinding = recoverInvalidCursor === true && typeof cursor === 'string' && cursor.length > 0
+        && error instanceof CloudError && error.code === 'INVALID_CURSOR' && error.status === 400;
+      if (!(error instanceof CloudError) || (error.code !== 'CURSOR_EXPIRED' && !invalidBinding)) throw error;
       const details = error.details ?? {};
       // The snapshot is taken FIRST. Only then does the cursor move, and the gap is recorded so
       // a reader can see that something happened here rather than inferring quiet.
       if (!feed.exportSnapshot) throw new CloudError('RESYNC_SNAPSHOT_UNAVAILABLE', 410, details);
       if (resynced) throw new CloudError('RESYNC_REPEATED_EXPIRY', 410, details);
-      let snapshot = null, snapshotCursor = null;
+      let snapshot = null, snapshotCursor = null, snapshotPages = 0;
       const seen = new Set();
       do {
+        if (snapshotPages >= maxPages) throw new CloudError('RESYNC_SNAPSHOT_LIMIT', 502);
         const part = await feed.exportSnapshot({cursor: snapshotCursor, limit: 100});
+        snapshotPages++;
         snapshot = snapshot ? {...snapshot, items: [...snapshot.items, ...(part.items ?? [])]} : {...part, items: part.items ?? []};
         snapshotCursor = part.next_cursor ?? null;
         if (snapshotCursor && seen.has(snapshotCursor)) throw new CloudError('INVALID_SNAPSHOT_CURSOR', 502);
@@ -128,10 +132,13 @@ async function pullFeed(feed, cursorKey, state, { maxPages = 100, onSnapshot = n
           data: {after}});
       }
       await onSnapshot?.(snapshot, cursorKey);
-      gaps.push({ at: new Date().toISOString(), reason: 'cursor_expired', resumed_from: details.resume_cursor ?? null });
-      cursor = details.resume_cursor ?? null;
+      // An invalid binding supplies no trusted watermark. Snapshot current state first,
+      // then replay the retained feed under the client's unchanged configured scope.
+      const resume = invalidBinding ? null : details.resume_cursor ?? null;
+      gaps.push({ at: new Date().toISOString(), feed: cursorKey, reason: invalidBinding ? 'cursor_invalid' : 'cursor_expired', resumed_from: resume });
+      cursor = resume;
       resynced = true;
-      if (!details.resume_cursor) break;
+      if (!invalidBinding && !resume) break;
       continue;
     }
     events.push(...(page.events ?? []));
@@ -139,6 +146,7 @@ async function pullFeed(feed, cursorKey, state, { maxPages = 100, onSnapshot = n
     // Applied, then advanced.
     cursor = page.next_cursor ?? cursor;
     if (!page.has_more) break;
+    if (resynced && pages >= maxPages) throw new CloudError('RESYNC_EVENT_LIMIT', 502);
   }
   // Named by feed, so a caller writing this back cannot put it under the wrong key.
   return { feed: cursorKey, events, cursor, pages, gaps, resynced };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentlinkops",
-  "version": "0.6.8",
-  "description": "A backlink and AI citation ledger that lives in your repository: local link and citation checks with dated evidence, supplier-export imports and optional sync to the hosted AgentLinkOps service.",
+  "version": "0.6.10",
+  "description": "Backlink checks with dated evidence and portable results, optional repository ledgers, supplier-export imports and sync to AgentLinkOps.",
   "author": "AgentLinkOps (https://agentlinkops.com)",
   "license": "Apache-2.0",
   "type": "module",
@@ -56,10 +56,13 @@
     "jsonl"
   ],
   "dependencies": {
+    "@modelcontextprotocol/client": "2.2.0",
     "@modelcontextprotocol/server": "2.0.0",
+    "ipaddr.js": "2.2.0",
+    "koffi": "3.3.2",
     "parse5": "8.0.1",
     "turndown": "^7.2.4",
-    "undici": "7.29.0",
+    "undici": "7.29.1",
     "zod": "4.6.0"
   },
   "devDependencies": {

package/references/cli.md

@@ -196,3 +196,25 @@ hide a history gap and is not a supported recovery procedure.
 All success output is JSON except requested CSV export. Errors are JSON on
 stderr with nonzero exit status. HTTP response bodies and credential values
 are never included in errors. Local operation has no telemetry.
+
+## Writer-lock recovery candidate
+
+The maintained development source adds verified-owner recovery for `sync.lock`
+and the ledger's secondary writer lock. This source acceptance is separate from
+an installed release and hosted/client acceptance. A persistent OS advisory gate
+serializes cooperating writers; valid same-user/same-boot metadata for a departed
+writer can be recovered. Marker age alone never authorizes removal. Live, reused,
+legacy empty, malformed or unverifiable markers are preserved with a refusal.
+
+Keep the local ledger, mirror and state files. Read-only `status`/`report` remain
+useful while writer ownership is unresolved. Inspect a copy; do not delete a live
+lock or signal a process you did not create. An uncertain cloud request still
+needs its original operation/readback before any write is retried; releasing a
+local lock does not prove the remote request failed.
+
+The candidate uses pinned prebuilt native assets for Darwin/Linux, with no compiler
+fallback in the package build. Actual crash and relocated-package acceptance is
+recorded for Darwin arm64; other architectures, Windows, musl and network-file
+systems require separate proof. Unsupported/native-unavailable writers fail
+closed with actionable setup diagnostics. Native lock acceptance does not enable
+Darwin OAuth custody or establish customer credentials/grants.

package/references/local-crm-draft-handoff.md

@@ -0,0 +1,76 @@
+# Local Outreach CRM draft handoff
+
+Use only when the customer selects a local Outreach CRM with an existing
+`projects/<crm_project>/config.json` and `drafts/` directory. The config must contain
+that exact `project` and a `site` URL with the same hostname as the request.
+This adapter writes an inert body and companion manifest under that project's
+drafts directory. It does not write contacts, replies, suppression, send logs or
+sequence state. Native vendor APIs remain unsupported by this adapter.
+
+Run from the plugin root:
+
+```sh
+python3 scripts/outreach-crm-draft.py --crm-root /path/to/customer-crm --request request.json --body-file reviewed-body.txt
+python3 scripts/outreach-crm-draft.py --crm-root /path/to/customer-crm --request request.json --body-file reviewed-body.txt --readback
+```
+
+`request.json` contains exactly these fields; use actual saved identities rather
+than copying the example values:
+
+```json
+{
+  "version": 1,
+  "crm_project": "customer-project",
+  "workspace_id": "saved-workspace",
+  "project_id": "saved-project",
+  "site": "https://customer.invalid",
+  "operation_id": "original-operation",
+  "original_request": {
+    "destination": "saved-service-destination",
+    "workspace_id": "saved-workspace",
+    "project_id": "saved-project",
+    "command": "saved-command",
+    "arguments": {"saved-non-secret-argument": "saved-value"},
+    "idempotency_key": "original-request-key"
+  },
+  "local_id": "saved-local-record",
+  "external_id": "saved-crm-record",
+  "observation": "unknown",
+  "reply": "unknown",
+  "suppression": "unknown",
+  "subject": "Reviewed draft subject",
+  "body_sha256": "exact-sha256-of-reviewed-body-bytes"
+}
+```
+
+Preserve the original request tuple from its checkpoint, including its exact
+non-secret arguments. Never place credentials in it. Workspace/project binding
+is customer supplied; this helper does not authenticate it against hosted grants
+or confirm that an external ID exists in CRM contacts. Its local config check
+prevents an explicit site/project mismatch, not a forged customer mapping.
+
+`observation` is `unknown`, `present`, `provisional_loss` or `confirmed_loss`;
+`reply` is `unknown`, `none` or `replied`; `suppression` is `unknown`, `clear` or
+`suppressed`. These are retained observations, not refreshed sender decisions.
+Drafts always have `send_eligible: false`, including apparently clear rows.
+Follow the qualified campaign recipe's content review before saving a real draft.
+
+The original operation and local/external identities determine one stable draft
+directory. The helper verifies the supplied UTF-8 body hash, publishes `body.txt`
+and `manifest.json`, then rereads their exact bytes. An identical retry reports
+`identical_readback`. If interrupted between files, repeat the original save;
+it completes the missing artifact without replacing the existing body. A changed
+subject, body, request or mapping at that identity refuses rather than overwrites.
+Inspect and preserve the conflicting original artifact; a legitimate new operation
+requires a separately recorded identity, not a fabricated replay key.
+
+`--readback` verifies both artifacts and refuses missing or partial saves. It does
+not create a draft directory. Keep the receipt's operation, destination directory,
+body and manifest hashes with the customer's checkpoint. Saving here is actual
+local filesystem destination readback, not a mailbox/vendor acknowledgement.
+
+Publication reuses the portable helper's cooperating-writer locking and ExFAT
+fallback. Destination symlinks are refused. This does not sandbox arbitrary local
+applications or prove power-loss durability. No email system or network dependency
+is installed. Current sender reply/suppression/quota/mailbox gates must still be
+checked by the customer's existing sender at its separately authorized send step.