agentlinkops 0.6.11 → 0.6.16

package/cli/check.js

@@ -12,23 +12,47 @@
 import { verifyLink } from '../src/verifier/index.js';
 import { observationRow } from './mirror.js';
 import { cadenceSeconds, DEFAULT_CADENCE } from './ledger.js';
+import { createNodePublicFetch } from './public-http.js';
+import { setTimeout as waitTimer } from 'node:timers/promises';
+import { VerificationError, withAbort } from '../src/page-acquisition/bytes.js';
 
-const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const sleep = async (ms, signal) => {
+  // Node's timer limit must not turn a very long publisher floor into 1 ms.
+  for (let remaining = ms; remaining > 0;) {
+    const duration = Math.min(remaining, 2_147_483_647);
+    try { await waitTimer(duration, undefined, { signal }); }
+    catch (error) { if (signal?.aborted) throw new VerificationError('timeout'); throw error; }
+    remaining -= duration;
+  }
+};
 const hostOf = url => { try { return new URL(url).hostname; } catch { return null; } };
 
+/** Private diagnostic prefixes are publisher bytes, even when HTML opt-out is set. */
+export function portableCheckObservation(result) {
+  const observed = structuredClone(result);
+  const diagnostics = [observed.robots, ...(observed.robotsHistory ?? []), observed.sourceResponse];
+  for (const item of diagnostics) if (item?.bodyDiagnostic) delete item.bodyDiagnostic.sampleText;
+  return observed;
+}
+
 /** A courtesy floor per host, honouring a publisher's own stated delay when it is longer. */
 export function createPacer({ hostDelayMs = 2000, now = () => Date.now(), wait = sleep } = {}) {
-  const nextAllowed = new Map();
+  const lastRequest = new Map();
   return {
     async beforeFetch(url, context = {}) {
+      if (context.signal?.aborted) throw new VerificationError('timeout');
       const host = hostOf(url);
       if (!host) return;
-      const stated = Number(context.crawlDelaySeconds ?? 0) * 1000;
-      const floor = Math.max(hostDelayMs, Number.isFinite(stated) ? stated : 0);
-      const allowed = nextAllowed.get(host) ?? 0;
+      const prior = lastRequest.get(host);
+      const stated = context.crawlDelaySeconds == null ? prior?.floor ?? 0 : Number(context.crawlDelaySeconds) * 1000;
+      const floor = Math.max(hostDelayMs, Number.isFinite(stated) ? stated : prior?.floor ?? 0);
+      // Robots was just fetched before its delay became known. Apply the new
+      // floor to that preceding request, not only to the following one.
+      const allowed = prior ? prior.at + Math.max(prior.floor, floor) : 0;
       const delay = allowed - now();
-      if (delay > 0) await wait(delay);
-      nextAllowed.set(host, now() + floor);
+      if (delay > 0) await withAbort(wait(delay, context.signal), context.signal);
+      if (context.signal?.aborted) throw new VerificationError('timeout');
+      lastRequest.set(host, { at: now(), floor });
     },
   };
 }
@@ -65,9 +89,14 @@ export function dueEntries(entries, lastChecked, { now = Date.now() } = {}) {
  */
 export async function runCheck(entries, {
   concurrency = 6, timeoutMs = 20_000, hostDelayMs = 2000,
-  verify = verifyLink, pacer = null, onResult = null,
+  verify = verifyLink, pacer = null, onResult = null, fetchImpl = null,
 } = {}) {
+  if (fetchImpl != null && typeof fetchImpl !== 'function') throw new TypeError('A local check transport must be a function.');
   const paced = pacer ?? createPacer({ hostDelayMs });
+  // A trusted in-process caller may supply a fixture transport. Normal CLI
+  // commands always use the pinned Node connector, independently of global fetch.
+  const nativeTransport = fetchImpl == null;
+  const localFetch = fetchImpl ?? createNodePublicFetch();
   const byHost = new Map();
   for (const entry of entries) {
     const host = hostOf(entry.source) ?? entry.id;
@@ -84,8 +113,9 @@ export async function runCheck(entries, {
             expectedAnchor: entry.expect?.anchor, expectedRel: entry.expect?.rel },
           // `includeHtml: false` is a contract commitment, not a size optimisation: the bytes
           // must not reach the repository.
-          { publicFetchSafe: true, timeoutMs, includeHtml: false, beforeFetch: paced.beforeFetch });
-        const row = observationRow(entry.id, result);
+          { publicFetchSafe: true, fetchImpl: localFetch, timeoutMs, includeHtml: false, beforeFetch: paced.beforeFetch,
+            ...(verify === verifyLink && nativeTransport ? { captureTransport: { id: 'local_node_http', version: 'alo-local-node-v1' } } : {}) });
+        const row = observationRow(entry.id, portableCheckObservation(result));
         rows.set(entry.id, row);
         onResult?.(entry, row);
       }

package/cli/chronology.js

@@ -0,0 +1,39 @@
+import {readFile,writeFile,mkdir,copyFile,unlink} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {dirname,resolve} from 'node:path';
+import {loadConfig,ConfigError} from './config.js';
+import {cloudConnection} from './connection.js';
+import {createClient} from './client.js';
+import {freezeChronology,normalizeLocalSubmissions} from '../shared/monitoring-chronology-export.js';
+const help='agentlinkops chronology pull --watch-id ID [--limit 50] [--cursor TOKEN] [--all] [--out NEW_FILE] | export --pages FILE [--submissions FILE] [--out NEW_FILE]';
+async function output(value,args,{cwd,out}){
+ const text=JSON.stringify(value,null,2)+'\n';
+ if(!args.out){out(text.trimEnd());return;}
+ if(typeof args.out!=='string'||!args.out.trim())throw new ConfigError('--out requires a file');
+ const path=resolve(cwd,args.out),temp=`${path}.${crypto.randomUUID()}.tmp`;
+ await mkdir(dirname(path),{recursive:true});
+ try{await writeFile(temp,text,{flag:'wx',mode:0o600});await copyFile(temp,path,constants.COPYFILE_EXCL);}finally{await unlink(temp).catch(e=>{if(e.code!=='ENOENT')throw e;});}
+ out(`wrote ${path}`);
+}
+export async function chronologyMain(args,{cwd=process.cwd(),env=process.env,fetchImpl=globalThis.fetch,out=console.log}={}){
+ const command=args._[1],allowed=new Set(['_','tag','watch-id','limit','cursor','all','out','pages','submissions']);
+ if(args._.length!==2||args.tag?.length||Object.keys(args).some(key=>!allowed.has(key)))throw new ConfigError(help);
+ if(command==='export'){
+  if(typeof args.pages!=='string'||args['watch-id']!==undefined||args.limit!==undefined||args.cursor!==undefined||args.all!==undefined)throw new ConfigError(help);
+  const input=JSON.parse(await readFile(resolve(cwd,args.pages),'utf8')),pages=Array.isArray(input)?input:[input];
+  const localItems=args.submissions?await normalizeLocalSubmissions(JSON.parse(await readFile(resolve(cwd,args.submissions),'utf8')),pages[0]?.identity):[];
+  await output(await freezeChronology(pages,{localItems}),args,{cwd,out});return 0;
+ }
+ if(command!=='pull'||typeof args['watch-id']!=='string'||args.pages!==undefined||args.submissions!==undefined||args.all!==undefined&&args.all!==true)throw new ConfigError(help);
+ const limit=Number(args.limit??50);if(!Number.isInteger(limit)||limit<1||limit>100||args.cursor===true)throw new ConfigError(help);
+ const config=await loadConfig({cwd}),connection=cloudConnection(config,env);
+ if(!connection.projectId)throw new ConfigError('Connect this project before reading hosted chronology.');
+ const client=createClient({...connection,fetchImpl}),pages=[];let cursor=args.cursor;
+ do{
+  const page=await client.callCommand('get_placement_chronology',{watchId:args['watch-id'],limit,...(cursor?{cursor}: {})});
+  if(page.identity?.projectId!==connection.projectId||page.identity?.watchId!==args['watch-id']||connection.workspaceId&&page.identity?.workspaceId!==connection.workspaceId)throw new ConfigError('Chronology identity does not match the connected project and selected watch.');
+  pages.push(page);cursor=page.nextCursor;
+  if(pages.length===100&&args.all&&cursor)throw new ConfigError('Chronology exceeds the 100-page read bound. Pull explicit pages and export their qualified partial dataset.');
+ }while(args.all&&cursor);
+ await output(args.all?await freezeChronology(pages):pages[0],args,{cwd,out});return 0;
+}

package/cli/client.js

@@ -5,7 +5,7 @@ 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.11';
+export const CLI_VERSION = '0.6.16';
 export const CLI_USER_AGENT = `agentlinkops-cli/${CLI_VERSION}`;
 const MAX_ATTEMPTS = 3;
 const MAX_RETRY_WAIT_MS = 5_000;
@@ -113,6 +113,7 @@ export function createClient({ origin, token, workspaceId, projectId, fetchImpl
     callCommand: (name, args = {}) => call('POST', `/v1/commands/${encodeURIComponent(name)}`, { body: args }),
     getWorkspace: () => call('GET', '/v1/workspace'),
     getProject: projectId => call('GET', `/v1/projects/${encodeURIComponent(projectId)}`),
+    listProjects: query => call('GET', '/v1/projects', { query }),
     importWatches: (projectId, watches) => call('POST', '/v1/watches/import', { body: { projectId, watches } }),
     updateWatch: (watchId, patch) => call('PATCH', `/v1/watches/${encodeURIComponent(watchId)}`, { body: patch }),
     listWatches: query => call('GET', '/v1/watches', { query: { ...query, ...(projectId ? { projectId } : {}) } }),

package/cli/commands.js

@@ -1,11 +1,11 @@
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { loadConfig, ConfigError } from './config.js';
-import { cloudConnection } from './connection.js';
+import { cloudConnection, DEFAULT_ORIGIN } from './connection.js';
 import { createClient, CloudError } from './client.js';
 import { parseArgs } from './args.js';
 import { NUDGE } from './skill.js';
-import { CATALOG_COMMANDS, CATALOG_TOOLSETS } from './catalog.js';
+import { CATALOG_COMMANDS, CATALOG_VERSION, CATALOG_TOOLSETS } from './catalog.js';
 import { oneLiner } from '../src/tool-views.js';
 import { resolveSchemaPath, listAvailablePaths } from '../shared/exec-grammar.js';
 
@@ -24,7 +24,7 @@ const NEXT = {
   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.',
-  NO_TOKEN: 'Set AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY from a project-scoped key.',
+  NO_TOKEN: 'Run `npx -y agentlinkops connect` once in a terminal and paste an API key from the Agent page; scripts can set AGENTLINKOPS_API_KEY instead.',
   PROVIDER_NOT_CONFIGURED: 'An operator must enable this supplier admission; retrying does not change it.',
   OWNED_DISCOVERY_NOT_CONFIGURED: 'An operator must configure owned discovery; retrying does not change it.',
   IDEMPOTENCY_CONFLICT: 'Reuse an idempotency key only with identical arguments; choose a new key for a new request.',
@@ -34,9 +34,16 @@ export const explain = code => NEXT[code] ?? 'Run `agentlinkops describe NAME` a
 export const resolveName = (commands, name) => commands.find(c => c.name === name) ?? commands.find(c => c.aliases?.includes(name)) ?? null;
 
 // The index: grouped by toolset, one line per command, core and write and admission marked.
+// Both forms drop per-command summaries when the complete index would exceed its token estimate
+// (2,000 for the terminal, 6,000 for JSON); one toolset keeps them, and describe has the rest.
 export function renderIndex(commands, { toolset = null, json = false } = {}) {
   const selected = toolset ? commands.filter(c => c.toolset === toolset) : commands;
-  if (json) return JSON.stringify({ toolsets: toolset ? { [toolset]: CATALOG_TOOLSETS[toolset] } : CATALOG_TOOLSETS, commands: selected.map(c => ({ name: c.name, toolset: c.toolset, tier: c.tier, readOnly: c.readOnly, summary: oneLiner(c.description, 64), ...(c.admissionGated ? { admission: 'gated' } : {}), ...(c.aliases?.length ? { aliases: c.aliases } : {}) })), next: 'Run `agentlinkops describe NAME` for a schema, then `agentlinkops call NAME --args JSON`.' });
+  if (json) {
+    const index = summaries => JSON.stringify({ version:CATALOG_VERSION,count:selected.length,toolsets: toolset ? { [toolset]: CATALOG_TOOLSETS[toolset] } : CATALOG_TOOLSETS, defaults: { tier: 'deferred' }, commands: selected.map(c => ({ name: c.name, toolset: c.toolset, ...(c.tier === 'deferred' ? {} : { tier: c.tier }), readOnly: c.readOnly, ...(summaries ? { summary: oneLiner(c.description, 40) } : {}), ...(c.admissionGated ? { admission: 'gated' } : {}), ...(c.aliases?.length ? { aliases: c.aliases } : {}) })),
+      next: (summaries ? '' : 'Run `agentlinkops tools TOOLSET` for one-line summaries. ') + 'Run `agentlinkops describe NAME` for a schema, then `agentlinkops call NAME --args JSON`.' });
+    const full = index(true);
+    return Math.round(full.length / 3.6) < 6000 ? full : index(false);
+  }
   const groups = new Map();
   for (const c of selected) (groups.get(c.toolset) ?? groups.set(c.toolset, []).get(c.toolset)).push(c);
   const lines = [];
@@ -46,7 +53,9 @@ export function renderIndex(commands, { toolset = null, json = false } = {}) {
     lines.push('');
   }
   lines.push(`${selected.length} commands${toolset ? ` in ${toolset}` : ''}. describe NAME shows the schema; call NAME --args JSON runs it.`);
-  return lines.join('\n');
+  const full = lines.join('\n');
+  if (Math.round(full.length / 3.6) < 2000) return full;
+  return lines.map(line => line.startsWith('  ') ? line.slice(0, line.indexOf('  ', 2)) : line).join('\n');
 }
 
 // One definition: what a describe_tools call returns, printed for a terminal or as JSON.
@@ -137,12 +146,12 @@ export async function commandsMain(argv, { cwd = process.cwd(), env = process.en
   // Catalog: bundled snapshot, or the live one when asked (needs a configured origin and key).
   let commands = CATALOG_COMMANDS, client = null;
   const connect = () => {
+    // The hosted service unless an origin is configured; the key decides the workspace.
     const connection = cloudConnection(loadConfigSync(), env);
-    if (!connection.origin) throw new CloudError('NO_CLOUD_ORIGIN', 0);
     let origin;
-    try { origin = new URL(connection.origin); } catch { throw new CloudError('INVALID_CLOUD_ORIGIN', 0); }
+    try { origin = new URL(connection.origin || DEFAULT_ORIGIN); } catch { throw new CloudError('INVALID_CLOUD_ORIGIN', 0); }
     if (origin.protocol !== 'https:' || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) throw new CloudError('INVALID_CLOUD_ORIGIN', 0);
-    return createClient({ ...connection, fetchImpl });
+    return createClient({ ...connection, origin: origin.origin, fetchImpl });
   };
   let loaded = null;
   const loadConfigSync = () => loaded;

package/cli/connection.js

@@ -1,5 +1,5 @@
 import { acquireSyncLock } from './sync-lock.js';
-import { readFile, writeFile, rename, unlink, open } from 'node:fs/promises';
+import { readFile, writeFile, rename, unlink, open, stat } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { loadConfig, ConfigError } from './config.js';
 import { createClient } from './client.js';
@@ -7,8 +7,10 @@ import { readLedger } from './ledger.js';
 import { resolveEnv } from './env.js';
 import { createOAuthCredentialStore } from './oauth-credentials.js';
 import { discoverOAuth, receiveOAuthConsent, exchangeOAuthCode } from './oauth-flow.js';
+import { API_KEY_PATTERN, STORED_KEY } from './key-store.js';
 
 export const SYNC_SCOPES = ['projects:read', 'watches:read', 'watches:write', 'events:read', 'exports:create'];
+export const DEFAULT_ORIGIN = 'https://app.agentlinkops.com';
 
 // Both TOKEN and API_KEY have shipped in customer installations, under both the AGENTLINKOPS_
 // and the LINKTRAIL_ prefix (env.js owns that alias rule). Reject ambiguous identities: a
@@ -22,9 +24,16 @@ 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.');
-  const origin = values.API_URL || config.cloud?.origin;
-  const token = values.TOKEN || values.API_KEY || config.cloud?.token;
+  let origin = values.API_URL || config.cloud?.origin;
+  let token = values.TOKEN || values.API_KEY || config.cloud?.token;
+  let tokenSource = values.TOKEN ? sources.TOKEN : values.API_KEY ? sources.API_KEY : null, storedKey = false;
   const auth = config.cloud?.auth;
+  // Otherwise the key `agentlinkops connect` saved for this origin, or for the default origin when
+  // none is configured. Only main() attaches the reader, so library callers and tests see none.
+  if (!token && auth === undefined && typeof env[STORED_KEY] === 'function') {
+    const saved = env[STORED_KEY](origin || DEFAULT_ORIGIN);
+    if (saved) ({ key: token, where: tokenSource } = saved), origin ||= DEFAULT_ORIGIN, storedKey = true;
+  }
   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.');
@@ -36,24 +45,58 @@ export function cloudConnection(config, env = process.env) {
       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,
+    token, tokenSource, ...(storedKey ? { storedKey } : {}),
     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. 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.`;
+  return `Create an API key on the Agent page (${origin}/#/access, Create API key), then run \`npx -y agentlinkops connect\` in a terminal and paste it when asked; the CLI keeps it outside your repository. Scripts and CI can supply it through AGENTLINKOPS_API_KEY instead (AGENTLINKOPS_TOKEN also works; the LINKTRAIL_ spellings remain accepted during the pilot compatibility window). Ledger sync needs the scopes ${SYNC_SCOPES.join(', ')}. 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.`;
+}
+
+const pastePrompt = origin => `Paste an API key from ${origin}/#/access (Create API key), or press Enter to cancel: `;
+
+/**
+ * The CLI half of connecting: a key that works, saved where cloud commands find it. Asks for one
+ * when none is available and a terminal is (ask), and again when a saved key stopped working.
+ * Verifies before saving; never prints the key. Returns null when there is no key to use.
+ */
+export async function connectKey({ origin, token = null, stored = false, ask = null, prompt = pastePrompt(origin), keyStore = null,
+  fetchImpl = globalThis.fetch, clientFactory = createClient, out = console.log }) {
+  let pasted = false, account;
+  for (;;) {
+    if (!token) {
+      token = ask ? String(await ask(prompt) ?? '').trim() : '';
+      if (!token) return null;
+      pasted = true;
+    }
+    if (!API_KEY_PATTERN.test(token))
+      throw new ConfigError(pasted ? 'That is not an AgentLinkOps API key (keys start with lt_). Create one on the Agent page and paste all of it.' : 'Supply a complete API key through AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY.');
+    try { account = await clientFactory({ origin, token, fetchImpl }).getWorkspace(); break; }
+    catch (error) {
+      if (!(stored && !pasted && ask && error?.status === 401)) throw error;
+      out('The saved key no longer works (revoked or expired).');
+      token = null;
+    }
+  }
+  if (typeof account?.workspace?.id !== 'string' || !account.workspace.id) throw new ConfigError('The cloud did not name the workspace this key belongs to.');
+  if (pasted) {
+    if (!keyStore) throw new ConfigError('This command cannot save a key here. Set AGENTLINKOPS_API_KEY instead.');
+    await keyStore.save(origin, token);
+    out(`Saved the key in ${keyStore.where}.`);
+  }
+  return { token, account, saved: pasted };
 }
 
 // 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,
   credentialStore = createOAuthCredentialStore(), oauth = { discoverOAuth, receiveOAuthConsent, exchangeOAuthCode },
-  onAuthorization = ({ authorizationUrl }) => out(`Authorize the connection: ${authorizationUrl}`), clientFactory = createClient } = {}) {
+  onAuthorization = ({ authorizationUrl }) => out(`Authorize the connection: ${authorizationUrl}`), clientFactory = createClient,
+  keyStore = null, ask = null } = {}) {
   const config = await loadConfig({ cwd });
   const connection = cloudConnection(config, env);
-  const origin = args.origin || connection.origin || 'https://app.agentlinkops.com';
-  const workspaceId = args.workspace || connection.workspaceId;
-  const projectId = args['project-id'] || connection.projectId;
+  const origin = args.origin || connection.origin || DEFAULT_ORIGIN;
+  let workspaceId = args.workspace || connection.workspaceId;
+  let projectId = args['project-id'] || connection.projectId;
   let parsed;
   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 !== '/')
@@ -62,13 +105,30 @@ export async function connectMain(args, { cwd, env = process.env, out = console.
   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)
+  if (oauthRequested && connection.token && !connection.storedKey) throw new ConfigError('Remove API-key credentials before selecting OAuth.');
+  if (config.cloud?.origin && new URL(config.cloud.origin).origin !== parsed.origin || connection.workspaceId && workspaceId !== connection.workspaceId || connection.projectId && projectId !== connection.projectId)
     throw new ConfigError('This ledger is connected elsewhere; use a separate ledger to preserve its cursors and mapping.');
+  if (oauthRequested && (typeof workspaceId !== 'string' || !workspaceId || typeof projectId !== 'string' || !projectId))
+    throw new ConfigError('connect --oauth requires --workspace ID and --project-id ID from the existing cloud project.');
+  // A key saved for one origin never travels to another.
+  let token = oauthRequested ? undefined : connection.storedKey && connection.origin !== parsed.origin ? env[STORED_KEY]?.(parsed.origin)?.key : connection.token;
+  const hasLedger = await stat(join(config.dir, 'config.json')).then(() => true, () => false);
+  let keyWhere = connection.storedKey ? connection.tokenSource : null;
+  if (!oauthRequested && (!token || !workspaceId)) {
+    // No IDs to look up: the key names its workspace. Without a ledger here, this connects the CLI
+    // for cloud commands in any folder; with one, it goes on to map the ledger to a website.
+    const key = await connectKey({ origin: parsed.origin, token, stored: connection.storedKey === true, ask, keyStore, fetchImpl, clientFactory, out });
+    if (!key) { out(keySetup(parsed.origin)); return 2; }
+    token = key.token;
+    if (key.saved) keyWhere = keyStore.where;
+    workspaceId ||= key.account.workspace.id;
+    if (!hasLedger && !projectId) {
+      out(`Connected the CLI to ${key.account.workspace.name || 'your workspace'}. Cloud commands work from any folder now, for example: agentlinkops call list_tasks`);
+      return 0;
+    }
+  }
+  if (!oauthRequested && !API_KEY_PATTERN.test(token)) throw new ConfigError('Supply a complete API key through AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY.');
+  if (!hasLedger) throw new ConfigError('No ledger here to map to a website: run `agentlinkops init` first, or omit --project-id to connect the CLI only.');
   let ledgerIds;
   if (args.selection !== undefined) {
     if (typeof args.selection !== 'string') throw new ConfigError('--selection requires a JSON file of ledger IDs or mapping entries.');
@@ -106,9 +166,23 @@ export async function connectMain(args, { cwd, env = process.env, out = console.
     }
   }
   try {
-  const client = clientFactory({ origin: parsed.origin, token: connection.token, ...(auth ? {auth, credentialStore} : {}), workspaceId, projectId, fetchImpl });
+  const client = clientFactory({ origin: parsed.origin, 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.');
+  if (!projectId) {
+    // Which website this ledger tracks: the key's only website, or the workspace's only one.
+    const allowed = account.access?.project_ids;
+    const projects = Array.isArray(allowed) && allowed.length === 1 ? null : ((await client.listProjects({ limit: 100 })).items ?? [])
+      .filter(project => !Array.isArray(allowed) || allowed.includes(project.id));
+    if (!projects) projectId = allowed[0];
+    else if (projects.length === 1) projectId = projects[0].id;
+    else {
+      out(projects.length
+        ? ['Choose the website this ledger tracks, then run its command:', ...projects.map(project => `  agentlinkops connect --project-id ${project.id}    # ${project.domain || project.name || project.id}`)].join('\n')
+        : `Add a website on ${parsed.origin}/#/websites first, then run agentlinkops connect again.`);
+      return 2;
+    }
+  }
   // 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(', ')}.`);
@@ -142,7 +216,7 @@ export async function connectMain(args, { cwd, env = process.env, out = console.
   }
   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.`);
+    : `Verified workspace ${workspaceId}, project ${projectId}. Saved connection metadata; ${keyWhere ? `the key stays in ${keyWhere}` : '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.

package/cli/contact-adoption.js

@@ -0,0 +1,91 @@
+import {createHash} from 'node:crypto';
+import {contactFields} from '../shared/contact-record-contract.js';
+
+const digest=value=>createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const fields=c=>({externalRef:c.externalRef,name:c.name,email:c.email,contactUrl:c.contactUrl});
+const equal=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+
+/** A contact-only bridge. Inputs are frozen exports; there are no source-CRM writes. */
+export function planContactAdoption({projectId,rows,contacts=[],links=[]}){
+ const seen=new Map(),results=[];
+ for(const [index,row]of rows.entries()){
+  const parsed=contactFields.safeParse(row.contact);
+  let reason=!parsed.success?'invalid_contact':null;
+  const contact=parsed.success?parsed.data:null;
+  const sameRef=contact?contacts.filter(c=>c.externalRef===contact.externalRef):[];
+  if(sameRef.length>1)reason='ambiguous_contact_reference';
+  if(contact&&seen.has(contact.externalRef)&&!equal(seen.get(contact.externalRef),contact))reason='conflicting_source_contact';
+  if(contact)seen.set(contact.externalRef,contact);
+  const matches=links.filter(l=>l.localReference===row.localReference);
+  if(!row.localReference||matches.length!==1)reason=matches.length>1?'ambiguous_link_reference':'link_reference_not_found';
+  const beforeContact=sameRef[0]??null,beforeLink=matches[0]??null;
+  if(beforeContact&&beforeContact.projectId!==projectId||beforeLink&&beforeLink.projectId!==projectId)reason='project_mismatch';
+  results.push({row:index+1,localReference:row.localReference??null,contact,beforeContact,beforeLink,status:reason?'conflict':'ready',reason});
+ }
+ // Reject every row in a conflicting identity group; input order cannot pick a winner.
+ const bad=new Set(results.filter(r=>r.reason==='conflicting_source_contact').map(r=>r.contact.externalRef));
+ for(const row of results)if(bad.has(row.contact?.externalRef)){row.status='conflict';row.reason='conflicting_source_contact';}
+ const byLink=new Map();
+ for(const row of results){if(!row.beforeLink)continue;const group=byLink.get(row.beforeLink.watchId)??[];group.push(row);byLink.set(row.beforeLink.watchId,group);}
+ for(const group of byLink.values())if(new Set(group.map(row=>row.contact?.externalRef)).size>1)for(const row of group){row.status='conflict';row.reason='conflicting_link_contact';}
+ const plan={schemaVersion:'agentlinkops-contact-adoption-v1',projectId,results,effects:{sourceWrites:0,emails:0,sequenceEnrollments:0,newWatches:0,checks:0}};
+ return{...plan,sha256:digest(plan)};
+}
+
+function verifyPlan(plan){const {sha256,...body}=plan;if(body.schemaVersion!=='agentlinkops-contact-adoption-v1'||digest(body)!==sha256)throw new Error('ADOPTION_PLAN_CHANGED');}
+/** Caller supplies the authenticated command transport; no credentials or mailbox are read here. */
+export async function applyContactAdoption(plan,call){
+ verifyPlan(plan);const results=[],effects={...plan.effects,confirmedContactWrites:0,confirmedAssociationWrites:0,rowsRequiringReadback:0};
+ for(const row of plan.results){
+  if(row.status!=='ready'){results.push({row:row.row,status:'conflict',reason:row.reason});continue;}
+  const base={projectId:plan.projectId};let saved=null,writeAttempted=false;
+  try{
+   const current=await call('list_contacts',{...base,externalRef:row.contact.externalRef,watchId:row.beforeLink.watchId,limit:2});
+   const contact=current.items[0]??null;
+   if(current.items.length>1)throw new Error('CONTACT_IDENTITY_CONFLICT');
+   // Exact desired content is a safe replay. A changed source preview never overwrites a human edit.
+   if(contact&&!equal(fields(contact),row.contact)&&(!row.beforeContact||contact.revision!==row.beforeContact.revision||!equal(fields(contact),fields(row.beforeContact))))throw new Error('CONTACT_CHANGED_SINCE_PREVIEW');
+   if(!contact&&row.beforeContact)throw new Error('CONTACT_REMOVED_SINCE_PREVIEW');
+   if(current.link?.contactId!==row.beforeLink.contactId&&current.link?.contactId!==contact?.id)throw new Error('LINK_CHANGED_SINCE_PREVIEW');
+   writeAttempted=true;saved=await call('save_contact',{...base,revision:contact?.revision??0,contact:row.contact});
+   if(!saved.replayed)effects.confirmedContactWrites++;
+   const linked=await call('set_link_contact',{...base,watchId:row.beforeLink.watchId,contactId:saved.contact.id,revision:current.link?.revision??0});
+   if(linked.revision!==(current.link?.revision??0))effects.confirmedAssociationWrites++;
+   results.push({row:row.row,status:'applied',contactId:saved.contact.id,contactRevision:saved.contact.revision,link:linked,replayed:saved.replayed,rollback:{beforeContact:row.beforeContact,beforeLink:row.beforeLink,afterContact:saved.contact,afterLink:linked}});
+  }catch(error){if(writeAttempted)effects.rowsRequiringReadback++;results.push({row:row.row,status:'conflict',reason:error.code??error.message,effectState:writeAttempted?'requires_readback':'none',...(saved?{contactSaved:true,contactId:saved.contact.id,contactRevision:saved.contact.revision}:{} )});}
+ }
+ return{schemaVersion:plan.schemaVersion,planSha256:plan.sha256,projectId:plan.projectId,results,effects};
+}
+
+/** Explicit compensating rollback. Concurrent edits hold the row; sender/source data is untouched. */
+export async function rollbackContactAdoption(receipt,call){
+ const results=[],effects={sourceWrites:0,emails:0,sequenceEnrollments:0,newWatches:0,checks:0,confirmedAssociationWrites:0,confirmedContactWrites:0,confirmedContactDeletes:0,rowsRequiringReadback:0};
+ for(const result of [...receipt.results].reverse()){
+  if(!result.rollback){results.push({row:result.row,status:'no_effect'});continue;}
+  const {beforeContact,beforeLink,afterContact,afterLink}=result.rollback,base={projectId:receipt.projectId};
+  try{
+   const current=await call('list_contacts',{...base,externalRef:afterContact.externalRef,watchId:afterLink.watchId,limit:2});
+   const contact=current.items[0];
+   if(current.link.contactId===beforeLink.contactId&&(!beforeContact&&!contact||beforeContact&&contact&&equal(fields(contact),fields(beforeContact)))){results.push({row:result.row,status:'already_restored'});continue;}
+   if(!contact||contact.revision!==afterContact.revision||!equal(fields(contact),fields(afterContact)))throw new Error('ROLLBACK_CONCURRENT_CHANGE');
+   if(current.link.contactId!==beforeLink.contactId){
+    if(current.link.contactId!==afterLink.contactId||current.link.revision!==afterLink.revision)throw new Error('ROLLBACK_CONCURRENT_CHANGE');
+    const restoredLink=await call('set_link_contact',{...base,watchId:afterLink.watchId,contactId:beforeLink.contactId,revision:afterLink.revision});
+    if(restoredLink.revision!==afterLink.revision)effects.confirmedAssociationWrites++;
+   }
+   // Newly created contacts can be shared by later rows. Restore/delete once, after all links.
+   results.push({row:result.row,status:'link_restored',contactId:afterContact.id,beforeContact,afterContact});
+  }catch(error){effects.rowsRequiringReadback++;results.push({row:result.row,status:'held',reason:error.code??error.message});}
+ }
+ const restored=new Set();
+ for(const row of results){
+  if(row.status!=='link_restored'||restored.has(row.contactId))continue;
+  // Do not erase a new contact if another row failed to detach; preserve useful partial state.
+  if(results.some(r=>r.status==='held'))continue;
+  restored.add(row.contactId);
+  try{if(row.beforeContact){const saved=await call('save_contact',{projectId:receipt.projectId,revision:row.afterContact.revision,contact:fields(row.beforeContact)});if(!saved.replayed)effects.confirmedContactWrites++;}
+   else {const removed=await call('delete_contact',{projectId:receipt.projectId,contactId:row.contactId,revision:row.afterContact.revision,onlyIfUnlinked:true});if(removed.deleted)effects.confirmedContactDeletes++;}row.status='restored';
+  }catch(error){effects.rowsRequiringReadback++;row.status='held';row.reason=error.code??error.message;}
+ }
+ return{planSha256:receipt.planSha256,results,effects};
+}

package/cli/context.js

@@ -19,7 +19,9 @@ import {
   readContextState, readGscRows, refreshContext, pageContext, selectFocusPages,
   importHandoff, forgetContext, createGoogleClient, recentWindows, windowFromRange,
 } from '../src/context/gsc.js';
-import { buildSiteProfile, renderSiteProfile, validateProfileCitations, readSiteFacts } from '../src/context/site-profile.js';
+import { buildSiteProfile, createSiteTransport, renderSiteProfile, validateProfileCitations, readSiteFacts } from '../src/context/site-profile.js';
+import { createAcquisition } from '../src/corpus/acquire.js';
+import { createNodePublicFetch } from './public-http.js';
 import {
   refreshGa4Context, landingPageContext, keyEventsContext, businessContextForPage,
   importGa4Handoff, forgetGa4Context, createGa4Client, readGa4Rows, GA4_SCOPE,
@@ -72,7 +74,7 @@ async function resolvePaths(cwd) {
   return { config, paths: contextPaths({ dir: config.dir, file }) };
 }
 
-export async function contextMain(argv = process.argv.slice(2), { cwd = process.cwd(), out = console.log, err = console.error, env = process.env } = {}) {
+export async function contextMain(argv = process.argv.slice(2), { cwd = process.cwd(), out = console.log, err = console.error, env = process.env, signal } = {}) {
   const args = parseArgs(argv);
   const area = args._[0] ?? 'help';
   const command = args._[1] ?? null;
@@ -273,9 +275,18 @@ export async function contextMain(argv = process.argv.slice(2), { cwd = process.
 
     if (area === 'profile') {
       if (command === 'build') {
+        // Node callers qualify their own public egress. Shared document/page
+        // primitives stay transport-injected and retain the existing budgets.
+        const fetchImpl = createNodePublicFetch();
+        const documents = createSiteTransport({ fetchImpl });
+        const transport = signal ? { fetchText: (url, options = {}) => documents.fetchText(url, { ...options,
+          signal: options.signal ? AbortSignal.any([options.signal, signal]) : signal }) } : documents;
         const result = await buildSiteProfile({
           site: args.site === true ? null : (args.site ?? null),
           paths, extraPages: args.page ?? [],
+          transport,
+          acquisition: createAcquisition({ fetchImpl, publicFetchSafe: true, purpose: 'research', directMethod: 'node_http', signal,
+            captureTransport: { id: 'local_node_http', version: 'alo-local-node-v1' } }),
         });
         if (args.json) { out(JSON.stringify(result, null, 1)); return 0; }
         out(`origin ${result.origin}: robots ${result.robots.outcome}${result.robots.reason ? ` (${result.robots.reason})` : ''}, ${result.sitemaps.documents} sitemap document(s), ${result.sitemaps.urls_found} URL(s)`);

package/cli/doctor.js

@@ -192,10 +192,19 @@ export async function doctorMain(argv = [], { cwd = process.cwd(), out = console
   // a legitimate local-only install, reported as a skip rather than a failure.
   const connection = cloudConnection(config, env);
   const origin = connection.origin || null;
+  const savedConnectionMetadata = config.cloud && typeof config.cloud === 'object'
+    && Object.keys(config.cloud).length > 0;
   const record = { at: new Date().toISOString() };
   let probed = false;
   if (!origin) {
-    checks.push({ status: 'skip', name: 'cloud', detail: 'no cloud configured (local-only repository)' });
+    if (savedConnectionMetadata) {
+      checks.push({ status: 'fail', name: 'connection',
+        detail: 'saved cloud metadata is present, but the CLI API connection is not configured',
+        fix: 'supply an API key through AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY, then run `agentlinkops connect` to verify the workspace and project. MCP clients keep their own OAuth credentials' });
+    }
+    checks.push({ status: 'skip', name: 'cloud', detail: savedConnectionMetadata
+      ? 'CLI API origin is missing; MCP access is separate'
+      : 'no cloud configured (local-only repository)' });
   } else {
     const cloud = await probeCloud({ origin, fetchImpl, timeoutMs });
     record.cloud = { ok: cloud.ok, status: cloud.status, ms: cloud.ms };
@@ -215,13 +224,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.auth ? 'the private OAuth credential store' : connection.tokenSource ? `the environment (${connection.tokenSource})` : `${config.dirName}/config.json (cloud.token)`;
+  const source = connection.auth ? 'the private OAuth credential store' : connection.storedKey ? `${connection.tokenSource}, saved by agentlinkops connect` : 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' });
+        fix: 'run `npx -y agentlinkops connect` in a terminal and paste an API key from the Agent page, or supply AGENTLINKOPS_API_KEY in the environment' });
     } else {
-      checks.push({ status: 'skip', name: 'token', detail: 'no token (and no cloud configured)' });
+      checks.push({ status: 'skip', name: 'token', detail: savedConnectionMetadata
+        ? 'no CLI API key is set; MCP credentials are managed by the MCP client'
+        : 'no token (and no cloud configured)' });
     }
   } 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)`,