agentlinkops 0.6.1 → 0.6.3

package/cli/citation.js

@@ -12,12 +12,17 @@ import { resolve, join } from 'node:path';
 
 import { parseArgs } from './args.js';
 import { loadPanel, runEpoch } from '../src/citations/runner.js';
-import { engineIdentity } from '../src/citations/contract.js';
+import { engineIdentity, panelLocaleContext } from '../src/citations/contract.js';
 import { createMockEngine, createPerplexityEngine, EngineError } from '../src/citations/adapter.js';
 import { describeChange } from '../src/citations/stats.js';
 
 const USAGE = `agentlinkops citation — AI citation watches in this repository
 
+  agentlinkops citation panel --domain HOST --brand NAME [--topic TOPIC]
+                                            [--prompt QUESTION | --research FILE --limit N] [--competitors FILE]
+                                            [--engine mock|chatgpt:web-own-browser|google-aio]
+                                            [--locale en-US] [--country US] [--out PANEL.json]
+                                            write editable prompt suggestions; mock is the default
   agentlinkops citation run PANEL.json [--dir DIR] [--samples N] [--max-usd USD] [--json]
                                             run one fixed-n epoch over a panel; evidence and
                                             tallies land under .agentlinkops/citations/
@@ -25,52 +30,137 @@ const USAGE = `agentlinkops citation — AI citation watches in this repository
                                             measure the consumer UI through Camoufox
                                             (dedicated account, personal cadence; evidence
                                             includes a screenshot of every answer)
-  agentlinkops citation report PANEL.json [--out FILE] [--dir DIR]
+  agentlinkops citation sweep PANEL.json --max-usd USD --out INVENTORY.json [--dir DIR]
+                                            run a bounded epoch and freeze its retained evidence
+  agentlinkops citation inventory PANEL.json --out INVENTORY.json [--epoch ID] [--dir DIR]
+                                            freeze an existing panel epoch without new calls
+  agentlinkops citation gap INVENTORY.json --out GAP.json
+                                            compare mentions and citations within this dataset
+  agentlinkops citation export-sources INVENTORY.json --niche ID --niche-label TEXT
+                                            --consent-ref REF --attest-owned --out SOURCES.json
+                                            export held library candidates; no publication
+  agentlinkops citation report PANEL.json [--out FILE] [--dir DIR] [--last N]
                                             render the latest epoch as a self-contained
                                             HTML report: trends, screenshots inline,
                                             Wilson intervals, honest classifications
   agentlinkops citation watch PANEL.json --cadence weekly|daily|hourly|monthly
+                                            [--webhook URL] [--out REPORT.html]
                                             register a cron entry that runs the epoch
                                             and generates the report on schedule
   agentlinkops citation watch --list         list registered citation watches
   agentlinkops citation watch --remove NAME  remove a registered watch
-  agentlinkops citation alert PANEL.json     check the latest epoch for declines;
+  agentlinkops citation alert PANEL.json [--webhook URL --report REPORT.html]
+                                            check the latest epoch for declines;
                                             logs an alert line if any cell declined
+  agentlinkops citation login ENGINE         open a browser, log in once, save the session
+                                            (the engine adapter uses it on every run)
+  agentlinkops citation logout ENGINE        remove a saved session
+  agentlinkops citation sessions            list saved engine sessions
+  agentlinkops citation sync [--dir DIR] [--evidence]  push local epoch rows to the hosted
+                                            API (requires agentlinkops connect first)
+                                            --evidence also uploads retained answer text;
+                                            screenshot bytes remain local
+  agentlinkops citation doctor               check local installation and browser dependencies
   agentlinkops citation help                 this help
 
 Panel (JSON): targets (domain or url, brand, aliases), prompts, engines
 ([{ "engine": "mock" | "perplexity", "model": "…" }]), optional samples and maxUsd.
-Live engines need the matching environment credential (PERPLEXITY_API_KEY); the mock
+Live engines need their configured credentials or a usable browser session; the mock
 engine runs everything at zero cost. Every run states its estimated spend, and the
-cap is checked BEFORE each call, so it can be approached but never exceeded.
+cap reserves estimated cost before each call. A supplier charge above that estimate
+is recorded as an overrun and stops subsequent calls.
 
 Output language: citation RATE with a Wilson interval and n, classified against the
 previous epoch as declined, grown or not_distinguishable — never "removed", never
 "stable", and insufficient_data when n is too thin to interpret.`;
 
 export async function citationMain(argv = [], { cwd = process.cwd(), out = console.log, err = console.error, env = process.env } = {}) {
-  const args = parseArgs(argv);
+  const args = parseArgs(argv, ['prompt', 'alias']);
   const command = args._[0] ?? 'help';
   if (command === 'help' || args.help) { out(USAGE); return 0; }
+  if (command === 'doctor') {
+    const { doctorMain } = await import('./doctor.js');
+    return doctorMain(args._.slice(1), { cwd, out, err, env });
+  }
+  if (command === 'panel') {
+    const { buildStarterPanel, selectResearchPrompts } = await import('../src/citations/panel-builder.js');
+    const { readFile, writeFile } = await import('node:fs/promises');
+    try {
+      if (args.research && args.prompt) throw new Error('Use either --research or --prompt');
+      const researched = args.research ? selectResearchPrompts(JSON.parse(await readFile(resolve(cwd, args.research), 'utf8')), { limit: args.limit === undefined ? 50 : Number(args.limit) }) : undefined;
+      const competitors = args.competitors ? JSON.parse(await readFile(resolve(cwd, args.competitors), 'utf8')) : [];
+      const selected = args.engine ?? 'mock';
+      const [engine, via] = selected.split(':');
+      if (!['mock', 'chatgpt', 'grok', 'duck', 'google-aio'].includes(engine) || (via && via !== 'web-own-browser')) throw new Error('unsupported panel engine');
+      if (['chatgpt', 'grok'].includes(engine) && via !== 'web-own-browser') throw new Error('browser engines require :web-own-browser');
+      const panel = buildStarterPanel({ domain: args.domain, brand: args.brand, topic: args.topic, aliases: args.alias ?? [],
+        competitors, engines: [{ engine, via: via ? 'browser' : 'api' }], locale: args.locale ?? 'en-US', country: args.country,
+        samples: args.samples === undefined ? 10 : Number(args.samples), maxUsd: args['max-usd'] === undefined ? 1 : Number(args['max-usd']),
+        prompts: researched ?? args.prompt?.map((text, index) => ({ id: `p${index + 1}`, text })),
+      });
+      const json = JSON.stringify(panel, null, 2) + '\n';
+      if (args.out) { await writeFile(resolve(cwd, args.out), json, { flag: 'wx' }); out(`panel written: ${args.out}`); }
+      else out(json);
+      err('Prompts are editable suggestions, not observed search demand. Review them before using a live engine.');
+      return 0;
+    } catch (cause) { err(cause.code === 'EEXIST' ? 'panel output already exists; choose another path' : cause.message); return 2; }
+  }
+  if (['sweep', 'inventory', 'gap', 'export-sources'].includes(command)) {
+    const { readFile, open, unlink } = await import('node:fs/promises');
+    const { freezeCitationInventory, citationGap, exportCitationSources } = await import('../src/citations/inventory.js');
+    let output;
+    try {
+      if (!args._[1] || typeof args.out !== 'string') throw new Error(`${command} requires an input file and --out FILE`);
+      if (command === 'sweep' && (args['max-usd'] === undefined || !Number.isFinite(Number(args['max-usd'])) || Number(args['max-usd']) <= 0)) throw new Error('sweep requires an explicit positive --max-usd ceiling');
+      // Reserve an exclusive output before a sweep can incur any measurement cost.
+      output = await open(resolve(cwd, args.out), 'wx', 0o600);
+      let result; let code = 0;
+      if (command === 'gap' || command === 'export-sources') {
+        const inventory = JSON.parse(await readFile(resolve(cwd, args._[1]), 'utf8'));
+        result = command === 'gap' ? citationGap(inventory) : await exportCitationSources(inventory, {
+          niche: { id: args.niche, label: args['niche-label'] }, consentRef: args['consent-ref'], excludedInputsAttested: args['attest-owned'] === true,
+        });
+      } else {
+        const panel = await loadPanel(resolve(cwd, args._[1]));
+        let epochId = args.epoch;
+        if (command === 'sweep') {
+          panel.maxUsd = Number(args['max-usd']);
+          let run;
+          code = await citationMain(['run', args._[1], '--dir', args.dir ?? '.agentlinkops', '--max-usd', String(args['max-usd']), '--json'], { cwd, env, err, out: value => { run = JSON.parse(value); } });
+          if (!run?.epochId) throw new Error('Sweep did not produce an epoch');
+          epochId = run.epochId;
+        }
+        result = await freezeCitationInventory({ dir: resolve(cwd, args.dir ?? '.agentlinkops'), panel, epochId });
+      }
+      await output.writeFile(JSON.stringify(result, null, 2) + '\n'); await output.close(); output = null;
+      out(`${command} written: ${args.out}`); return code;
+    } catch (cause) {
+      if (output) { await output.close(); await unlink(resolve(cwd, args.out)).catch(() => {}); }
+      err(cause.code === 'EEXIST' ? 'Output already exists; choose another path' : cause.message); return 2;
+    }
+  }
   if (command === 'alert') {
     const panelPath = args._[1];
     if (!panelPath) { err('citation alert needs a panel file'); return 2; }
     const { readFile } = await import('node:fs/promises');
     const dir = resolve(cwd, args.dir ?? '.agentlinkops');
-    let latestEpochId = null;
-    try {
-      const epochsText = await readFile(join(dir, 'citations-epochs.jsonl'), 'utf8');
-      const rows = epochsText.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
-      if (rows.length > 0) latestEpochId = rows[rows.length - 1].epoch_id;
-    } catch { /* no epochs */ }
-    if (!latestEpochId) { out('no epochs to check'); return 0; }
+    const { latestPanelEpoch } = await import('../src/citations/report.js');
+    const panel = await loadPanel(resolve(cwd, panelPath));
+    const cells = await latestPanelEpoch({ dir, panel });
+    if (!cells) { out('no epochs to check for this panel'); return 0; }
     const { shouldAlert } = await import('../src/citations/alert.js');
-    const epochsText = await readFile(join(dir, 'citations-epochs.jsonl'), 'utf8');
-    const cells = epochsText.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l)).filter((r) => r.epoch_id === latestEpochId);
     if (shouldAlert(cells)) {
       const declined = cells.filter((c) => c.classification === 'declined');
       err(`ALERT: ${declined.length} cell${declined.length === 1 ? '' : 's'} declined:`);
-      for (const c of declined) err(`  ${c.cell_id}: rate ${c.rate.toFixed(2)} (was ${c.baseline?.rate?.toFixed(2) ?? 'n/a'})`);
+      for (const c of declined) err(`  ${c.cell_id}: rate ${c.rate?.toFixed(2) ?? 'unknown'} (was ${c.baseline?.rate?.toFixed(2) ?? 'n/a'})`);
+      if (args.webhook) {
+        const { sendAlertWebhook } = await import('../src/citations/alert.js');
+        try {
+          const htmlPath = resolve(cwd, args.report ?? join(dir, 'citations', 'report.html'));
+          await sendAlertWebhook({ endpoint: args.webhook, epochId: cells[0].epoch_id, cells, htmlPath });
+          out('citation decline report delivered');
+        } catch { err('citation webhook delivery failed'); return 2; }
+      }
       return 1; // exit 1 = actionable, same convention as link checks
     }
     out('no declines detected');
@@ -93,7 +183,7 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
     if (!panelPath) { err('citation watch needs a panel file (or --list / --remove)'); return 2; }
     const cadence = args.cadence ?? 'weekly';
     try {
-      const result = await registerWatch({ panelPath, cadence });
+      const result = await registerWatch({ panelPath: resolve(cwd, panelPath), cadence, dir: resolve(cwd, args.dir ?? '.agentlinkops'), out: args.out ? resolve(cwd, args.out) : undefined, webhook: args.webhook });
       out(`citation watch registered: ${result.panelPath}`);
       out(`cadence: ${result.cadence} (${result.next})`);
       out(`cron: ${result.cronSpec}`);
@@ -103,22 +193,81 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
       return 2;
     }
   }
+  if (command === 'login') {
+    const engineName = args._[1];
+    if (!engineName) { err('citation login needs an engine name (e.g. chatgpt)'); return 2; }
+    const { loginEngine } = await import('../src/citations/login.js');
+    try {
+      const result = await loginEngine({ engineName });
+      out(`session saved: ${result.sessionPath}`);
+      out(`cookies: ${result.cookies}, origins: ${result.origins}, login detected: ${result.loggedIn}`);
+      return 0;
+    } catch (cause) { err(cause.message); return 2; }
+  }
+  if (command === 'logout') {
+    const engineName = args._[1];
+    if (!engineName) { err('citation logout needs an engine name'); return 2; }
+    const { logoutEngine } = await import('../src/citations/login.js');
+    const result = await logoutEngine({ engineName });
+    out(result.removed ? `session removed: ${engineName}` : `no session found for ${engineName}`);
+    return 0;
+  }
+  if (command === 'sessions') {
+    const { listSessions } = await import('../src/citations/login.js');
+    const sessions = await listSessions();
+    if (sessions.length === 0) { out('no saved sessions'); return 0; }
+    for (const s of sessions) out(s);
+    return 0;
+  }
+  if (command === 'sync') {
+    const dir = resolve(cwd, args.dir ?? '.agentlinkops');
+    const { createClient } = await import('./client.js');
+    const { cloudConnection } = await import('./connection.js');
+    const { readFile } = await import('node:fs/promises');
+    const { join } = await import('node:path');
+    try {
+      const { loadConfig } = await import('./config.js');
+      const config = await loadConfig({ cwd });
+      const connection = cloudConnection(config, env);
+      if (!connection.token) { err('citation sync needs a cloud connection (run agentlinkops connect)'); return 2; }
+      const { syncEpochs } = await import('../src/citations/sync.js');
+      const client = createClient(connection);
+      const result = await syncEpochs({
+        dir,
+        api: async (path, init) => client.callCommand(path.replace('/v1/commands/', ''), init.body),
+        workspaceId: connection.workspaceId,
+        projectId: connection.projectId,
+      });
+      out(`synced: ${result.synced}/${result.total} epoch rows${result.errors ? `, ${result.errors} errors` : ''}`);
+      if (result.normalized_rates) out(`${result.normalized_rates} legacy rates normalized: ${result.normalization}`);
+      if (args.evidence) {
+        const { syncEvidence } = await import('../src/citations/sync.js');
+        const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+        const evidence = await syncEvidence({ dir, projectId: connection.projectId, cliVersion: manifest.version,
+          api: async (path, init) => client.callCommand(path.replace('/v1/commands/', ''), init.body) });
+        out(`evidence synced: ${evidence.synced}/${evidence.total}, ${evidence.skipped} skipped, ${evidence.errors} errors; screenshot bytes remain local`);
+        for (const [reason, count] of Object.entries(evidence.reasons)) out(`${reason}: ${count}`);
+        if (evidence.errors || evidence.skipped) return 2;
+      }
+      return result.errors ? 1 : 0;
+    } catch (cause) { err(cause.message); return 2; }
+  }
   if (command === 'report') {
     const panelPath = args._[1];
     if (!panelPath) { err('citation report needs a panel file'); return 2; }
     const dir = resolve(cwd, args.dir ?? '.agentlinkops');
     const { generateReport } = await import('../src/citations/report.js');
     const { readFile, writeFile: wf } = await import('node:fs/promises');
-    // Find the latest epoch for this panel by reading the epochs file
-    let latestEpochId = null;
-    try {
-      const epochsText = await readFile(join(dir, 'citations-epochs.jsonl'), 'utf8');
-      const rows = epochsText.split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
-      if (rows.length > 0) latestEpochId = rows[rows.length - 1].epoch_id;
-    } catch { /* no epochs yet */ }
-    if (!latestEpochId) { err('no epochs found — run an epoch first'); return 2; }
-    const panel = JSON.parse(await readFile(resolve(cwd, panelPath), 'utf8'));
-    const html = await generateReport({ dir, epochId: latestEpochId, panel });
+    const panel = await loadPanel(resolve(cwd, panelPath));
+    const last = args.last === undefined ? 1 : Number(args.last);
+    if (args.last === true || !Number.isSafeInteger(last) || last < 1 || last > 30) {
+      err('citation report --last must be an integer from 1 to 30'); return 2;
+    }
+    const { panelEpochs } = await import('../src/citations/report.js');
+    const history = (await panelEpochs({ dir, panel })).slice(0, last);
+    if (!history.length) { err('no epochs found for this panel — run an epoch first'); return 2; }
+    const latestEpochId = history[0][0].epoch_id;
+    const html = await generateReport({ dir, epochId: latestEpochId, panel, history });
     const outPath = args.out ? resolve(cwd, args.out) : join(dir, 'citations', `report-${latestEpochId.slice(0, 15)}.html`);
     const { dirname, join: j } = await import('node:path');
     const { mkdir } = await import('node:fs/promises');
@@ -127,7 +276,7 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
     out(`report written: ${outPath} (${Math.round(html.length / 1024)} KB, self-contained)`);
     return 0;
   }
-  if (command !== 'run') { err(`unknown citation command: ${command}`); err(USAGE); return 2; }
+  if (!['run', 'report', 'watch', 'alert', 'login', 'logout', 'sessions', 'sync'].includes(command)) { err(`unknown citation command: ${command}`); err(USAGE); return 2; }
 
   const panelPath = args._[1];
   if (!panelPath) { err('citation run needs a panel file'); return 2; }
@@ -170,14 +319,14 @@ export async function citationMain(argv = [], { cwd = process.cwd(), out = conso
     if (spec.engine === 'mock') {
       engines.set(identity, createMockEngine({ fixtures: panel.mockFixtures ?? {} }));
     } else if (spec.engine === 'google-aio') {
-      // Fixture-first: runs against the recorded response with no credentials.
-      // Activates live the moment DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD exist.
+      // Live observations require explicit provider configuration; offline runs use mock.
       const { createGoogleAioEngine } = await import('../src/citations/adapter.js');
       const creds = env.DATAFORSEO_LOGIN && env.DATAFORSEO_PASSWORD
         ? { login: env.DATAFORSEO_LOGIN, password: env.DATAFORSEO_PASSWORD }
         : null;
-      engines.set(identity, createGoogleAioEngine({ credentials: creds }));
-      if (!creds) err(`google-aio: fixture mode (set DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD for live)`);
+      if (!creds) { err('google-aio requires DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD; select mock for offline runs'); return 2; }
+      const context = panelLocaleContext(panel, spec);
+      engines.set(identity, createGoogleAioEngine({ credentials: creds, country: context.country, languageCode: context.locale.split('-')[0] }));
     } else if (spec.engine === 'duck') {
       // Self-hosted Duck2api on the VPS: the whole Claude family plus GPT-5.6
       // anonymously through duck.ai. Localhost endpoint, no key.

package/cli/client.js

@@ -2,7 +2,7 @@ import {restResponseContract} from '../shared/response-contract.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.5.1';
+export const CLI_VERSION = '0.6.3';
 export const CLI_USER_AGENT = `agentlinkops-cli/${CLI_VERSION}`;
 export class CloudError extends Error {
   constructor(code, status, details = null) {

package/cli/commands.js

@@ -33,13 +33,13 @@ export const resolveName = (commands, name) => commands.find(c => c.name === nam
 // The index: grouped by toolset, one line per command, core and write and admission marked.
 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, 96), ...(c.admissionGated ? { admission: 'gated' } : {}), ...(c.aliases?.length ? { aliases: c.aliases } : {}) })), next: 'Run `agentlinkops describe NAME` for a schema, then `agentlinkops call NAME --args JSON`.' }, null, 2);
+  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`.' });
   const groups = new Map();
   for (const c of selected) (groups.get(c.toolset) ?? groups.set(c.toolset, []).get(c.toolset)).push(c);
   const lines = [];
   for (const [group, members] of [...groups].sort()) {
-    lines.push(CATALOG_TOOLSETS[group] ? `${group}: ${CATALOG_TOOLSETS[group]}` : `${group}:`);
-    for (const c of members.sort((a, b) => a.name.localeCompare(b.name))) lines.push(`  ${c.name}${c.tier === 'core' ? ' (core)' : ''}${c.readOnly ? '' : ' [write]'}${c.admissionGated ? ' [admission-gated]' : ''}  ${oneLiner(c.description, 48)}`);
+    lines.push(CATALOG_TOOLSETS[group] ? `${group}: ${oneLiner(CATALOG_TOOLSETS[group], 44)}` : `${group}:`);
+    for (const c of members.sort((a, b) => a.name.localeCompare(b.name))) lines.push(`  ${c.name}${c.tier === 'core' ? ' (core)' : ''}${c.readOnly ? '' : ' [write]'}${c.admissionGated ? ' [admission-gated]' : ''}  ${oneLiner(c.description, 22)}`);
     lines.push('');
   }
   lines.push(`${selected.length} commands${toolset ? ` in ${toolset}` : ''}. describe NAME shows the schema; call NAME --args JSON runs it.`);

package/cli/config.js

@@ -19,6 +19,7 @@ export const DEFAULTS = Object.freeze({
   ledger: 'links.jsonl',
   receipts: 'receipts.jsonl',
   observations: 'observations.jsonl',
+  indexObservations: 'index-observations.jsonl',
   events: 'events.jsonl',
   candidates: 'candidates.jsonl',
   state: 'state.json',
@@ -98,7 +99,7 @@ export async function loadConfig({ cwd = process.cwd(), root = null } = {}) {
     defaults: { ...DEFAULTS, ...file.defaults },
     paths: {
       ledger: at('ledger'), observations: at('observations'), events: at('events'),
-      candidates: at('candidates'), state: at('state'), receipts: at('receipts'),
+      candidates: at('candidates'), state: at('state'), receipts: at('receipts'), indexObservations: at('indexObservations'),
     },
   };
 }

package/cli/disavow.js

@@ -0,0 +1,54 @@
+import {open,unlink} from 'node:fs/promises';
+import {resolve} from 'node:path';
+import {createHash} from 'node:crypto';
+import {loadConfig,ConfigError} from './config.js';
+import {cloudConnection} from './connection.js';
+import {createClient,CloudError} from './client.js';
+import * as C from '../shared/disavow-contract.js';
+
+export const DISAVOW_USAGE='disavow list|history|propose --kind domain|url --value VALUE|import FILE|export [--out FILE]|approve|reject|delete --rule-id ID --revision N [--project-id ID]';
+const bad=message=>{throw new ConfigError(message);};
+export async function disavowMain(args,{cwd=process.cwd(),env=process.env,fetchImpl=globalThis.fetch,out=console.log}={}){
+ const action=args._[1];if(!action||action==='help'){out(DISAVOW_USAGE);return 0;}
+ const schemas={list:C.disavowListInput,history:C.disavowHistoryInput,propose:C.disavowProposeInput,import:C.disavowImportInput,export:C.disavowProjectInput,approve:C.disavowReviewInput,reject:C.disavowReviewInput,delete:C.disavowDeleteInput};
+ const names={list:'list_disavow_rules',history:'list_disavow_exports',propose:'propose_disavow_rule',import:'import_disavow_rules',export:'export_disavow_rules',approve:'review_disavow_rule',reject:'review_disavow_rule',delete:'delete_disavow_rule'};
+ if(!schemas[action])bad(DISAVOW_USAGE);
+ const options={list:['limit','cursor','status'],history:['limit','cursor'],propose:['kind','value','comment'],import:[],export:['out'],approve:['rule-id','revision'],reject:['rule-id','revision'],delete:['rule-id','revision']}[action];
+ if(Object.keys(args).some(key=>!['_','tag','json','project-id',...options].includes(key))||args.tag?.length||args._.length!==(action==='import'?3:2))bad(DISAVOW_USAGE);
+ const config=await loadConfig({cwd}),connection=cloudConnection(config,env),projectId=args['project-id']??connection.projectId;
+ let input={projectId};
+ if(action==='list'||action==='history')input={...input,...(args.limit===undefined?{}:{limit:Number(args.limit)}),...(args.cursor===undefined?{}:{cursor:args.cursor}),...(args.status===undefined?{}:{status:args.status})};
+ if(action==='propose')input={...input,kind:args.kind,value:args.value,source:'agent_proposal',status:'proposed',...(args.comment===undefined?{}:{comments:[`# ${args.comment}`]})};
+ if(['approve','reject','delete'].includes(action))input={...input,ruleId:args['rule-id'],revision:Number(args.revision),...(action==='delete'?{}:{decision:action})};
+ if(action==='import'){
+  const file=await open(resolve(cwd,args._[2]),'r');try{if((await file.stat()).size>C.DISAVOW_LIMITS.importBytes)bad('Disavow import exceeds 160 KiB.');input.text=await file.readFile('utf8');}finally{await file.close();}
+ }
+ const parsed=schemas[action].safeParse(input);if(!parsed.success)bad(`Invalid ${action} arguments. ${DISAVOW_USAGE}`);
+ const client=createClient({...connection,fetchImpl});
+ // Reserve both local artifacts before creating a remote export receipt. Existing
+ // customer files are never replaced and a path error cannot consume an export.
+ let target,receiptFile,targetPath,receiptPath,received=false;
+ if(action==='export'&&args.out!==undefined){
+  if(typeof args.out!=='string'||!args.out)bad('--out requires a file path.');
+  targetPath=resolve(cwd,args.out);receiptPath=`${targetPath}.receipt.json`;
+  target=await open(targetPath,'wx');try{receiptFile=await open(receiptPath,'wx');}catch(error){await target.close();await unlink(targetPath);throw error;}
+ }
+ try{
+  const result=await client.callCommand(names[action],parsed.data);
+  if(action==='export'){
+   const checked=C.disavowExportOutput.parse(result);
+   if(createHash('sha256').update(checked.text).digest('hex')!==checked.receipt.sha256||Buffer.byteLength(checked.text)!==checked.receipt.byte_length)throw new CloudError('INVALID_RESPONSE',502);
+   received=true;
+   if(target){await target.writeFile(checked.text,'utf8');await receiptFile.writeFile(JSON.stringify(checked.receipt,null,2)+'\n','utf8');out(JSON.stringify({file:targetPath,receiptFile:receiptPath,receipt:checked.receipt}));}
+   else out(JSON.stringify(checked));
+  }else out(JSON.stringify(result));
+  return 0;
+ }catch(error){
+  if(error.code==='HUMAN_ADMIN_REQUIRED')throw new ConfigError('Approve, reject or delete this rule in Disavow using the signed-in owner/admin console. Agent credentials cannot approve rules.');
+  if(received)out(JSON.stringify({error:{code:'DISAVOW_ARTIFACT_WRITE_FAILED',message:'The hosted export receipt exists. Inspect export history before retrying; local output may be incomplete.'}}));
+  throw error;
+ }finally{
+  await target?.close();await receiptFile?.close();
+  if(target&&!received){await unlink(targetPath).catch(()=>{});await unlink(receiptPath).catch(()=>{});}
+ }
+}

package/cli/doctor.js

@@ -252,14 +252,13 @@ export async function doctorMain(argv = [], { cwd = process.cwd(), out = console
       checks.push({ status: 'skip', name: 'token', detail: `set in ${source}; not verified (cloud unreachable)` });
     }
   }
-  // Citation engines: presence only, never the value. A missing credential is a skip,
-  // not a failure — the mock engine runs everything, and a repository that never set a
-  // live key has not broken anything it asked for.
-  if (env.PERPLEXITY_API_KEY) {
-    checks.push({ status: 'ok', name: 'citations', detail: 'PERPLEXITY_API_KEY is set; live citation runs available' });
-  } else {
-    checks.push({ status: 'skip', name: 'citations', detail: 'no engine credential set; mock citation runs work, live runs need PERPLEXITY_API_KEY' });
-  }
+  // Doctor does not contact citation providers or validate saved browser sessions.
+  // Environment presence must not imply an engine can run successfully.
+  const aioCredentials = Boolean(env.DATAFORSEO_LOGIN && env.DATAFORSEO_PASSWORD);
+  checks.push({
+    status: 'skip', name: 'citations',
+    detail: `${aioCredentials ? 'google-aio credentials are set but unverified; ' : ''}live engines were not checked; configure the selected engine credentials or browser session. Mock runs work offline`,
+  });
 
   // Browser engines: the Camoufox stack. Each missing piece names its fix; none
   // of it fails doctor, because API and mock engines do not need it.

package/cli/index-observations.js

@@ -0,0 +1,89 @@
+import {readFile,writeFile,open,rename,unlink,mkdir,stat} from 'node:fs/promises';
+import {dirname,resolve} from 'node:path';
+import {createHash} from 'node:crypto';
+import {loadConfig,ConfigError} from './config.js';
+import {cloudConnection} from './connection.js';
+import {createClient} from './client.js';
+import {parseCsv} from './adapters/csv.js';
+import {indexEvidenceReference,describeEvidenceReference} from '../src/evidence-reference.js';
+import {indexReceiptResponse} from '../shared/index-observation-contract.js';
+const sha=value=>createHash('sha256').update(value).digest('hex');
+const fail=message=>{throw new ConfigError(message);};
+export const INDEX_CLI_HELP='agentlinkops index pull --watch-id ID [--limit 50] [--before ID] | import RECEIPTS.json | export [--out FILE] | csv URLS.csv [--out FILE] | check-csv URLS.csv --connection-id ID --request-id ID --out FILE';
+function validate(row){
+ if(row?.v!==1||! /^[\w-]{1,128}$/.test(row.project_id??'')||! /^[\w-]{1,128}$/.test(row.watch_id??''))fail('Invalid local index receipt scope');
+ const receipt=indexReceiptResponse.parse(row.receipt);
+ if(receipt.observation.checked_at!==receipt.observation.checkedAt||receipt.observation.observation_id!==receipt.observation.observationId||!Number.isFinite(Date.parse(receipt.observation.checkedAt)))fail('Index receipt observation identity mismatch');
+ if(receipt.evidenceAvailable&&receipt.rawResponse==null)fail('Available index evidence requires an actual raw response');
+ if(!receipt.evidenceAvailable&&receipt.rawResponse!==null)fail('Unavailable index evidence must not contain a raw body');
+ if(receipt.evidenceAvailable&&sha(JSON.stringify(receipt.rawResponse))!==receipt.observation.evidenceSha256)fail('Index receipt payload hash mismatch');
+ return {...row,receipt};
+}
+async function atomicOutput(path,text){await mkdir(dirname(path),{recursive:true});const temporary=`${path}.${crypto.randomUUID()}.tmp`;try{await writeFile(temporary,text,{flag:'wx'});await rename(temporary,path);}finally{await unlink(temporary).catch(()=>{});}}
+async function boundedText(path){const info=await stat(path);if(info.size>32*1024*1024)fail('Index input exceeds 32 MiB; split the export');return readFile(path,'utf8');}
+export async function readIndexReceipts(path){
+ let text;try{text=await boundedText(path);}catch(error){if(error.code==='ENOENT')return [];throw error;}
+ return text.split('\n').filter(line=>line.trim()).map(line=>validate(JSON.parse(line)));
+}
+export async function saveIndexReceipts(path,rows){
+ const checked=rows.map(validate);await mkdir(dirname(path),{recursive:true});let lock;
+ try{lock=await open(`${path}.lock`,'wx');}catch(error){if(error.code==='EEXIST')fail('Index receipt writer already locked');throw error;}
+ const temporary=`${path}.${crypto.randomUUID()}.tmp`;
+ try{
+  const existing=await readIndexReceipts(path),byId=new Map(existing.map(r=>[r.receipt.observation.id,r]));
+  for(const row of checked){const id=row.receipt.observation.id,previous=byId.get(id);if(previous){
+   if(previous.project_id!==row.project_id||previous.watch_id!==row.watch_id||JSON.stringify(previous.receipt.observation)!==JSON.stringify(row.receipt.observation))fail('Index receipt identity conflict');
+   if(previous.receipt.evidenceAvailable&&!row.receipt.evidenceAvailable)continue;
+  }byId.set(id,row);}
+  const text=[...byId.values()].sort((a,b)=>a.receipt.observation.id.localeCompare(b.receipt.observation.id)).map(r=>JSON.stringify(r)).join('\n')+'\n';if(Buffer.byteLength(text)>32*1024*1024)fail('Local index receipts exceed 32 MiB; archive before importing more');
+  await writeFile(temporary,text,{flag:'wx'});await rename(temporary,path);return {saved:checked.length,total:byId.size};
+ }finally{await unlink(temporary).catch(()=>{});await lock.close();await unlink(`${path}.lock`);}
+}
+export function locateIndexReceipt(rows,receiptId){
+ const row=rows.find(r=>r.receipt.observation.id===receiptId);if(!row)fail('No local index receipt matches this reference');
+ const reference=indexEvidenceReference({receiptId});
+ return {...row.receipt,projectId:row.project_id,watchId:row.watch_id,evidence_reference:reference,reference_resolution:describeEvidenceReference(reference),notes:['Retained index evidence describes the provider snapshot at its check date, not a live crawl.','This explicit local export survives hosted cancellation; hosted raw retention does not remove customer-owned copies.']};
+}
+export function indexRowsForUrl(rows,url){
+ const latest=new Map();for(const row of rows){const o=row.receipt.observation;if(o.url!==url)continue;const previous=latest.get(o.source_key);if(!previous||o.checked_at>previous.checked_at||(o.checked_at===previous.checked_at&&o.id>previous.id))latest.set(o.source_key,{...o,locator:indexEvidenceReference({receiptId:o.id}),hosted_locator:indexEvidenceReference({receiptId:o.id,projectId:row.project_id,watchId:row.watch_id,storage:'hosted'})});}
+ return [...latest.values()].sort((a,b)=>a.source_key.localeCompare(b.source_key));
+}
+const cell=value=>{const raw=String(value??''),safe=/^[\s]*[=+\-@]|^[\t\r]/.test(raw)?`'${raw}`:raw;return `"${safe.replaceAll('"','""')}"`;};
+export function indexCsv(urls,receipts){
+ const output=[['URL','Verdict','Reason','Check Date','Confidence','Backend','Evidence Reference']];
+ for(const url of urls){const rows=indexRowsForUrl(receipts,url);if(!rows.length)output.push([url,'unknown','not_checked','','unknown','','']);else for(const row of rows)output.push([url,row.tier,row.reason,row.checked_at,row.confidence,row.backend,row.locator]);}
+ return output.map(row=>row.map(cell).join(',')).join('\r\n')+'\r\n';
+}
+function csvInput(text){
+ const [header,...rows]=parseCsv(text),urlAt=header?.findIndex(v=>['url','source_url'].includes(v.trim().toLowerCase())),watchAt=header?.findIndex(v=>v.trim().toLowerCase()==='watch_id');
+ if(urlAt==null||urlAt<0||!rows.length||rows.length>100)fail('Index CSV requires URL or source_url and 1–100 rows');
+ return rows.map(row=>{let url;try{url=new URL(row[urlAt]);}catch{fail('Invalid index CSV URL');}if(!['https:','http:'].includes(url.protocol)||url.username||url.password||url.hash)fail('Invalid index CSV URL');return {url:url.href,watchId:watchAt>=0?row[watchAt]:null};});
+}
+export async function indexMain(args,{cwd=process.cwd(),env=process.env,out=console.log,fetchImpl=globalThis.fetch}={}){
+ const command=args._[1],config=await loadConfig({cwd}),path=config.paths.indexObservations;
+ const allowed=new Set(['_','tag','out','watch-id','limit','before','connection-id','request-id']);if(args.tag?.length||Object.keys(args).some(key=>!allowed.has(key)))fail(INDEX_CLI_HELP);
+ if(command==='import'){
+  if(!args._[2])fail(INDEX_CLI_HELP);const parsed=JSON.parse(await boundedText(resolve(cwd,args._[2])));if(!Array.isArray(parsed)||parsed.length>100)fail('Import requires an array of at most 100 scoped index receipts');out(JSON.stringify(await saveIndexReceipts(path,parsed)));return 0;
+ }
+ if(command==='export'){const text=JSON.stringify(await readIndexReceipts(path),null,2);if(args.out){if(typeof args.out!=='string')fail('--out requires a file');await atomicOutput(resolve(cwd,args.out),text);}else out(text);return 0;}
+ if(command==='csv'||command==='check-csv'){
+  if(!args._[2])fail(INDEX_CLI_HELP);const input=csvInput(await boundedText(resolve(cwd,args._[2])));
+  if(command==='check-csv'){
+   if(typeof args['connection-id']!=='string'||typeof args.out!=='string'||typeof args['request-id']!=='string'||! /^[\x21-\x7e]{1,128}$/.test(args['request-id'])||input.some(r=>!r.watchId))fail('check-csv requires watch_id for every row, --connection-id, --request-id and --out');
+   const connection=cloudConnection(config,env);if(!connection.projectId)fail('Connect this repository to a project first');const client=createClient({...connection,fetchImpl});
+   // Validate every supplied URL/watch pairing before the first inspection.
+   for(const row of input){const watch=await client.callCommand('get_link_watch',{watchId:row.watchId});if(watch.project_id!==connection.projectId||watch.source_url!==row.url)fail('CSV URL/watch scope mismatch; no inspection was started');}
+   const batchKey=sha(JSON.stringify([connection.projectId,args['connection-id'],args['request-id'],input]));
+   for(const row of input){const result=await client.callCommand('inspect_index_status',{connectionId:args['connection-id'],watchId:row.watchId,idempotencyKey:`csv-${sha(JSON.stringify([batchKey,row.watchId,row.url]))}`});await saveIndexReceipts(path,[{v:1,project_id:connection.projectId,watch_id:row.watchId,receipt:{observation:result.observation,rawResponse:result.rawResponse,evidenceAvailable:result.evidenceAvailable}}]);}
+  }
+  const csv=indexCsv(input.map(r=>r.url),await readIndexReceipts(path));if(args.out){if(typeof args.out!=='string')fail('--out requires a file');const target=resolve(cwd,args.out);await atomicOutput(target,csv);}else out(csv);return 0;
+ }
+ if(command==='pull'){
+  if(typeof args['watch-id']!=='string')fail(INDEX_CLI_HELP);const limit=Number(args.limit??50);if(!Number.isInteger(limit)||limit<1||limit>100)fail('Index pull limit must be 1–100');
+  const connection=cloudConnection(config,env);if(!connection.projectId)fail('Connect this repository to a project first');const client=createClient({...connection,fetchImpl});
+  const page=await client.callCommand('list_index_observations',{projectId:connection.projectId,watchId:args['watch-id'],limit,...(args.before?{beforeId:args.before}:{})});const rows=[];
+  for(const observation of page.observations)rows.push({v:1,project_id:connection.projectId,watch_id:args['watch-id'],receipt:await client.callCommand('get_index_observation',{projectId:connection.projectId,watchId:args['watch-id'],receiptId:observation.id})});
+  out(JSON.stringify({...await saveIndexReceipts(path,rows),nextCursor:page.nextCursor}));return 0;
+ }
+ fail(INDEX_CLI_HELP);
+}

package/cli/ledger.js

@@ -6,6 +6,7 @@
 // number that is wrong in a way they discover months later.
 import { readFile, writeFile, mkdir, rename, open, unlink } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import {lifecycleDeal,emptyDeal} from '../shared/lifecycle-contract.js';
 
 export const INTENTS = Object.freeze(['wanted', 'expected', 'retired']);
 export const SCOPES = Object.freeze(['exact', 'domain', 'subdomain', 'path']);
@@ -17,7 +18,7 @@ export const DEFAULT_CADENCE = Object.freeze({ wanted: 'weekly', expected: 'dail
 
 // Stable key order, so `fmt` produces a diff that names the entry that changed rather than
 // reordering every line.
-const KEY_ORDER = ['id', 'intent', 'source', 'target', 'scope', 'expect', 'cadence', 'ref', 'origin', 'tags', 'added', 'note'];
+const KEY_ORDER = ['id', 'intent', 'source', 'target', 'scope', 'expect', 'cadence', 'ref', 'origin', 'tags', 'added', 'note', 'deal'];
 
 // Where an entry came from, when it was not typed by hand. `placement_run` is adopt-side
 // lineage, not import-side: a run's queue holds decisions already made and its output reports
@@ -115,6 +116,11 @@ export function normalizeEntry(input, { assignId = false } = {}) {
       else entry[field] = input[field];
     }
   }
+  if ('deal' in input) {
+    const parsed=lifecycleDeal.safeParse(input.deal===null?emptyDeal():input.deal);
+    if(!parsed.success)problems.push('deal must contain valid lifecycle fields with paired cost/currency');
+    else entry.deal=parsed.data;
+  }
   // An unknown key is kept rather than discarded: it is the customer's file, and a future
   // version of this tool may well mean something by it.
   for (const [key, value] of Object.entries(input)) if (!KEY_ORDER.includes(key)) entry[key] = value;