agentlinkops 0.6.2 → 0.6.4

package/cli/citation.js

@@ -65,7 +65,7 @@ const USAGE = `agentlinkops citation — AI citation watches in this repository
 
 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 reserves estimated cost before each call. A supplier charge above that estimate
 is recorded as an overrun and stops subsequent calls.

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.6.2';
+export const CLI_VERSION = '0.6.4';
 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`.' });
+  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, 36)}`);
+    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

@@ -20,6 +20,7 @@ export const DEFAULTS = Object.freeze({
   receipts: 'receipts.jsonl',
   observations: 'observations.jsonl',
   indexObservations: 'index-observations.jsonl',
+  indexSubmissions: 'index-submissions.jsonl',
   events: 'events.jsonl',
   candidates: 'candidates.jsonl',
   state: 'state.json',
@@ -99,7 +100,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'), indexObservations: at('indexObservations'),
+      candidates: at('candidates'), state: at('state'), receipts: at('receipts'), indexObservations: at('indexObservations'), indexSubmissions: at('indexSubmissions'),
     },
   };
 }

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

@@ -1,3 +1,4 @@
+import {boundedSubmissionText,readSubmissions,saveSubmissions,reconcileSubmissions,submissionCsv} from './index-submissions.js';
 import {readFile,writeFile,open,rename,unlink,mkdir,stat} from 'node:fs/promises';
 import {dirname,resolve} from 'node:path';
 import {createHash} from 'node:crypto';
@@ -9,7 +10,7 @@ import {indexEvidenceReference,describeEvidenceReference} from '../src/evidence-
 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';
+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 | submissions-import FILE | submissions-export --project-id ID [--out FILE] | reconcile-submissions --project-id ID [--format json|csv] [--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);
@@ -61,6 +62,19 @@ function csvInput(text){
 }
 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;
+ if(['submissions-import','submissions-export','reconcile-submissions'].includes(command)){
+  const allowed=new Set(['_','tag','out','project-id','format']);
+  if(args.tag?.length||Object.keys(args).some(key=>!allowed.has(key))||args._.length!==(command==='submissions-import'?3:2))fail(INDEX_CLI_HELP);
+  if(command==='submissions-import'){
+   if(args.out||args['project-id']||args.format)fail(INDEX_CLI_HELP);
+   out(JSON.stringify(await saveSubmissions(config.paths.indexSubmissions,JSON.parse(await boundedSubmissionText(resolve(cwd,args._[2]))))));return 0;
+  }
+  if(args.format&&!['json','csv'].includes(args.format))fail('Submission format must be json or csv');
+  if(command==='submissions-export'&&args.format)fail(INDEX_CLI_HELP);
+  const report=reconcileSubmissions(await readSubmissions(config.paths.indexSubmissions),command==='reconcile-submissions'?await readIndexReceipts(path):[],args['project-id']);
+  const text=command==='submissions-export'?JSON.stringify(report.submissions.map(({outcome,observations,verification,...row})=>row),null,2):args.format==='csv'?submissionCsv(report):JSON.stringify(report,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;
+ }
  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;

package/cli/index-submissions.js

@@ -0,0 +1,50 @@
+import {readFile,writeFile,open,rename,unlink,mkdir,stat} from 'node:fs/promises';
+import {dirname} from 'node:path';
+import {createHash} from 'node:crypto';
+import {ConfigError} from './config.js';
+import {indexEvidenceReference} from '../src/evidence-reference.js';
+const fail=message=>{throw new ConfigError(message);};
+const digest=value=>createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const id=value=>typeof value==='string'&&/^[\w-]{1,128}$/.test(value);
+const fields=['v','id','project_id','url','channel','endpoint','submitted_at','http_status','evidence_sha256'];
+export const SUBMISSION_NOTE='Imported submission records describe reported HTTP responses. Hashes check local integrity, not provider authenticity. Later Google observations do not verify indexing by an IndexNow participant or show that submission caused indexing.';
+export function validateSubmission(row){
+ if(!row||Object.keys(row).some(k=>!fields.includes(k))||fields.some(k=>!Object.hasOwn(row,k))||row.v!==1||!id(row.id)||!id(row.project_id)||row.channel!=='indexnow'||row.endpoint!=='https://api.indexnow.org/indexnow')fail('Invalid IndexNow submission receipt');
+ let url;try{url=new URL(row.url);}catch{fail('Invalid submission URL');}
+ if(typeof row.url!=='string'||url.href!==row.url||!['https:','http:'].includes(url.protocol)||url.username||url.password||url.hash)fail('Submission URL must be exact HTTP(S) without credentials or fragment');
+ if(typeof row.submitted_at!=='string'||!Number.isFinite(Date.parse(row.submitted_at))||new Date(row.submitted_at).toISOString()!==row.submitted_at)fail('Submission date must be an ISO UTC timestamp');
+ if(row.http_status!==null&&(!Number.isInteger(row.http_status)||row.http_status<100||row.http_status>599))fail('Invalid submission HTTP status');
+ const body=Object.fromEntries(fields.filter(k=>k!=='evidence_sha256').map(k=>[k,row[k]]));
+ if(row.evidence_sha256!==digest(body))fail('Submission receipt hash mismatch');
+ return {...body,evidence_sha256:row.evidence_sha256};
+}
+export async function boundedSubmissionText(path){const info=await stat(path);if(info.size>32*1024*1024)fail('Submission input exceeds 32 MiB');return readFile(path,'utf8');}
+export async function readSubmissions(path){try{return (await boundedSubmissionText(path)).split('\n').filter(line=>line.trim()).map(line=>validateSubmission(JSON.parse(line)));}catch(error){if(error.code==='ENOENT')return [];throw error;}}
+export async function saveSubmissions(path,rows){
+ if(!Array.isArray(rows)||rows.length>100)fail('Import requires at most 100 submission receipts');
+ const checked=rows.map(validateSubmission);await mkdir(dirname(path),{recursive:true});let lock;
+ try{lock=await open(`${path}.lock`,'wx');}catch(error){if(error.code==='EEXIST')fail('Submission receipt writer already locked');throw error;}
+ const tmp=`${path}.${crypto.randomUUID()}.tmp`;
+ try{
+  const current=await readSubmissions(path),byId=new Map(current.map(r=>[`${r.project_id}:${r.id}`,r]));
+  for(const row of checked){const key=`${row.project_id}:${row.id}`,old=byId.get(key);if(old&&JSON.stringify(old)!==JSON.stringify(row))fail('Submission receipt identity conflict');byId.set(key,row);}
+  const text=[...byId.values()].sort((a,b)=>a.project_id.localeCompare(b.project_id)||a.submitted_at.localeCompare(b.submitted_at)||a.id.localeCompare(b.id)).map(r=>JSON.stringify(r)).join('\n')+'\n';
+  if(Buffer.byteLength(text)>32*1024*1024)fail('Submission receipts exceed 32 MiB; archive before importing more');
+  await writeFile(tmp,text,{flag:'wx'});await rename(tmp,path);return {imported:checked.length,total:byId.size};
+ }finally{await unlink(tmp).catch(()=>{});await lock.close();await unlink(`${path}.lock`);}
+}
+export function reconcileSubmissions(submissions,observations,projectId){
+ if(!id(projectId))fail('A valid --project-id is required');
+ return {v:1,project_id:projectId,note:SUBMISSION_NOTE,submissions:submissions.filter(r=>r.project_id===projectId).map(validateSubmission).map(row=>{
+  const subsequent=observations.filter(r=>r.project_id===projectId&&r.receipt.observation.url===row.url&&Date.parse(r.receipt.observation.checked_at)>Date.parse(row.submitted_at)).map(r=>{
+   const o=r.receipt.observation;return {watch_id:r.watch_id,observation_id:o.id,checked_at:o.checked_at,backend:o.backend,source_key:o.source_key,tier:o.tier,reason:o.reason,confidence:o.confidence,evidence_sha256:o.evidenceSha256,evidence_available:r.receipt.evidenceAvailable,evidence_reference:indexEvidenceReference({receiptId:o.id}),relationship:'observation_after_submission',participant_indexing_verified:false,causation_established:false};
+  }).sort((a,b)=>a.checked_at.localeCompare(b.checked_at)||a.observation_id.localeCompare(b.observation_id));
+  return {...row,outcome:row.http_status===200?'received':row.http_status===202?'key_validation_pending':row.http_status===null?'unknown':'failed',observations:subsequent,verification:'not_established'};
+ })};
+}
+const cell=value=>{const raw=String(value??''),safe=/^[\s]*[=+\-@]|^[\t\r]/.test(raw)?`'${raw}`:raw;return `"${safe.replaceAll('"','""')}"`;};
+export function submissionCsv(report){
+ const rows=[['Project','Submission ID','URL','Submitted At','HTTP Status','Submission Outcome','Submission Hash','Observation ID','Watch ID','Backend','Source','Check Date','Verdict','Reason','Confidence','Evidence Available','Observation Hash','Evidence Reference','Participant Indexing Verified','Causation Established','Reading Note']];
+ for(const s of report.submissions)for(const o of s.observations.length?s.observations:[null])rows.push([report.project_id,s.id,s.url,s.submitted_at,s.http_status,s.outcome,s.evidence_sha256,o?.observation_id,o?.watch_id,o?.backend,o?.source_key,o?.checked_at,o?.tier??'unknown',o?.reason??'no_later_observation',o?.confidence??'unknown',o?.evidence_available??false,o?.evidence_sha256,o?.evidence_reference,false,false,report.note]);
+ return rows.map(row=>row.map(cell).join(',')).join('\r\n')+'\r\n';
+}

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;

package/cli/lifecycle.js

@@ -0,0 +1,40 @@
+import {legacyCostPatch} from '../shared/lifecycle-money.js';
+import {readFile,stat} from 'node:fs/promises';
+import {resolve} from 'node:path';
+import {loadConfig,ConfigError} from './config.js';
+import {cloudConnection} from './connection.js';
+import {createClient} from './client.js';
+import * as C from '../shared/lifecycle-contract.js';
+export const LIFECYCLE_CLI_HELP=`agentlinkops lifecycle get WATCH_ID
+agentlinkops lifecycle update WATCH_ID --revision N --deal PATCH.json [--decimal-cost]
+agentlinkops lifecycle clear WATCH_ID --revision N
+agentlinkops lifecycle renew [--limit 100]
+agentlinkops lifecycle report [--from YYYY-MM-DD] [--to YYYY-MM-DD]
+Uses the connected project. Deal costs are integer currency minor units. Null clears a field; costMinor and currency must be set or cleared together. Clear removes deal metadata, not the watch. Renew retains due events without sending a message. --decimal-cost reads cost_amount as an exact decimal string and cost_currency using the supported currency scale. sync --lifecycle pulls a deal mirror without editing the ledger.`;
+const fail=message=>{throw new ConfigError(message);};
+const integer=(value,name)=>{if(typeof value!=='string'||!/^\d+$/.test(value)||!Number.isSafeInteger(Number(value)))fail(`${name} requires a nonnegative integer`);return Number(value);};
+export async function lifecycleMain(args,{cwd=process.cwd(),env=process.env,out=console.log,fetchImpl=globalThis.fetch}={}){
+ if(args.help){out(LIFECYCLE_CLI_HELP);return 0;}
+ const action=args._?.[1],allowed={get:[],update:['revision','deal','decimal-cost'],clear:['revision'],renew:['limit'],report:['from','to']}[action];
+ if(!allowed||args.tag?.length||Object.keys(args).some(key=>!['_','tag',...allowed].includes(key)))fail(LIFECYCLE_CLI_HELP);
+ const record=['get','update','clear'].includes(action);
+ if(args._.length!==(record?3:2)||record&&(typeof args._[2]!=='string'||!args._[2]))fail(LIFECYCLE_CLI_HELP);
+ const config=await loadConfig({cwd}),connection=cloudConnection(config,env);if(!connection.projectId)fail('Connect this repository to a project first');
+ const input={projectId:connection.projectId};let name,schema,output;
+ if(record)input.watchId=args._[2];
+ if(action==='get'){name='get_link_lifecycle';schema=C.lifecycleGetInput;output=C.lifecycleOutput;}
+ if(action==='update'||action==='clear'){
+  name='update_link_lifecycle';schema=C.lifecycleUpdateInput;output=C.lifecycleOutput;input.revision=integer(args.revision,'--revision');
+  if(action==='clear')input.deal=C.emptyDeal();else{
+   if(typeof args.deal!=='string')fail('--deal requires a JSON patch file');const path=resolve(cwd,args.deal),info=await stat(path);if(!info.isFile()||info.size>16384)fail('Deal patch must be a JSON file of at most 16 KiB');
+   try{input.deal=JSON.parse(await readFile(path,'utf8'));}catch{fail('Deal patch must contain valid JSON');}
+   if(args['decimal-cost']){try{input.deal=legacyCostPatch(input.deal);}catch(e){fail(e.message);}}
+   const patch=C.lifecyclePatch.safeParse(input.deal);if(!patch.success)fail('Invalid deal patch fields');
+   if(('costMinor' in input.deal)!==('currency' in input.deal))fail('Set or clear costMinor and currency together');
+  }
+ }
+ if(action==='renew'){name='record_lifecycle_renewals';schema=C.lifecycleRenewInput;output=C.lifecycleRenewOutput;if(args.limit!==undefined)input.limit=integer(args.limit,'--limit');}
+ if(action==='report'){name='get_lifecycle_report';schema=C.lifecycleReportInput;output=C.lifecycleReportOutput;for(const key of ['from','to'])if(args[key]!==undefined)input[key]=args[key];}
+ const parsed=schema.safeParse(input);if(!parsed.success)fail('Invalid lifecycle dates, fields or bounds');
+ const result=await createClient({...connection,fetchImpl}).callCommand(name,parsed.data),checked=output.safeParse(result);if(!checked.success)fail('Invalid lifecycle service response');out(JSON.stringify(checked.data,null,2));return 0;
+}

package/cli/main.js

@@ -1,4 +1,7 @@
+import {lifecycleMain} from './lifecycle.js';
+import {admissionMain} from './admission.js';
 import { commandsMain } from './commands.js';
+import { disavowMain } from './disavow.js';
 import { agentMain } from './agent-setup.js';
 import { setupPlanMain } from './setup-plan.js';
 import {parseArgs as parseArguments} from './args.js';
@@ -19,7 +22,7 @@ import { readImport, parseMap } from './import.js';
 import { freezeDataset, renderReport, datasetDigest } from './report.js';
 import { createClient, CloudError } from './client.js';
 import { cloudConnection, connectMain, keySetup } from './connection.js';
-import { syncPlan, pushExpectations, pullEvents, cloudObservationRows, watchIndex, pullTargetEvents } from './sync.js';
+import { syncPlan, pushExpectations, pullLifecycleMirrors, pullEvents, cloudObservationRows, watchIndex, pullTargetEvents } from './sync.js';
 import { SUPPLIER_NAMES } from './adapters/suppliers.js';
 import { fleetSummary, renderFleet } from './fleet.js';
 import { platformAggregate, classifyObservation, renderPlatforms, attachToCandidates, PLATFORM_CLASSES } from './platforms.js';
@@ -49,7 +52,12 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
   agentlinkops add --source URL --target URL [--intent wanted|expected] [--scope …]
                 [--anchor TEXT] [--rel a,b] [--ref TEXT] [--tag t --tag t] [--note TEXT]
   agentlinkops index pull --watch-id ID [--limit N] [--before ID]
+  agentlinkops lifecycle get|update|clear|renew|report
+  agentlinkops admission list|add|update|remove|evaluate|reevaluate|receipt --project ID
+  agentlinkops disavow list|history|propose|import|export|approve|reject|delete
   agentlinkops index import FILE | export [--out FILE] | csv URLS.csv [--out FILE]
+  agentlinkops index submissions-import FILE | submissions-export --project-id ID [--out FILE]
+  agentlinkops index reconcile-submissions --project-id ID [--format json|csv] [--out FILE]
   agentlinkops index check-csv URLS.csv --connection-id ID --request-id ID --out FILE
   agentlinkops import FILE --target DOMAIN [--from SUPPLIER] [--map source=COL,target=COL]
                 [--exact-url] [--no-subdomains] [--generated-at ISO] [--json]
@@ -67,7 +75,7 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
   agentlinkops citation run PANEL.json [--dir DIR] [--samples N] [--max-usd USD] [--json]
                                             one fixed-n AI-citation epoch; evidence under
                                             .agentlinkops/citations/; live engines need
-                                            PERPLEXITY_API_KEY, the mock engine costs nothing
+                                            engine-specific setup; the mock engine makes no paid calls
   agentlinkops receive --body FILE --headers FILE   signed notification; authenticated pull
   agentlinkops connect --workspace ID --project-id ID [--origin URL] [--selection FILE]
   agentlinkops tools [TOOLSET] [--json] [--refresh]   cloud commands by toolset (offline snapshot;
@@ -80,7 +88,9 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
                                             detected agent client (Claude Code, Codex, Cursor,
                                             Gemini CLI, Hermes); stores no credential
   agentlinkops agent status                 what is installed where
-  agentlinkops sync [--push-only] [--pull-only] [--dry-run] [--include-wanted]
+  agentlinkops agent remove [--scope project|user] [--apply] [--json]
+  agentlinkops agent recover [--scope project|user] [--apply] [--json]
+  agentlinkops sync [--push-only] [--pull-only] [--dry-run] [--include-wanted] [--lifecycle]
                                             AGENTLINKOPS_TOKEN or AGENTLINKOPS_API_KEY
   agentlinkops check [--filter TEXT] [--all] [--json] [--fail-on-unknown]
   agentlinkops doctor                       verify ledger, verifier, cloud reachability, token
@@ -137,9 +147,12 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
 
   let syncLock = null;
   try {
+    if (command === 'lifecycle') return await lifecycleMain(args,{cwd,env,fetchImpl,out});
+    if (command === 'admission') { const config=await loadConfig({cwd}); return await admissionMain(argv.slice(1),{client:createClient({...cloudConnection(config,env),fetchImpl}),out,err}); }
+    if (command === 'disavow') return await disavowMain(args,{cwd,env,fetchImpl,out});
     if (command === 'index') return await indexMain(args,{cwd,env,fetchImpl,out});
     if (command === 'setup') return await setupPlanMain(argv, { cwd, out });
-    if (command === 'tools' || command === 'describe' || command === 'call') return await commandsMain(argv, { cwd, out, err });
+    if (command === 'tools' || command === 'describe' || command === 'call') return await commandsMain(argv, { cwd, out, err, env, fetchImpl });
     if (command === 'skill') return await skillMain(argv, { out });
     if (command === 'agent') return await agentMain(argv, { cwd, out, err });
     if (command === 'connect') {
@@ -517,6 +530,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       }
       const state = await readState(config.paths.state);
       if (args['pull-only'] && args['push-only']) throw new ConfigError('Choose --pull-only or --push-only.');
+      if(args.lifecycle&&args['push-only'])throw new ConfigError('--lifecycle requires a pull; omit --push-only.');
       const selection = { includeWanted: args['include-wanted'] === true, ledgerIds: config.cloud?.ledgerIds ?? null };
       if (args['dry-run']) { out(JSON.stringify({ network: false, rows: args['pull-only'] ? [] : syncPlan(ledger.entries, state, selection) }, null, 2)); return 0; }
       const connection = cloudConnection(config);
@@ -546,6 +560,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
         // expiry on one cannot move the other.
         const targets = await pullTargetEvents(client, next);
         const index = await watchIndex(client, next);
+        if(args.lifecycle)next.lifecycle=await pullLifecycleMirrors(client,next,{projectId:connection.projectId,index,ledgerIds:selection.ledgerIds??ledger.entries.map(entry=>entry.id)});
         const { fresh, duplicates } = await persistPulledHistory(config, pulled.events, targets.events, index);
         next.cursors = { ...(next.cursors ?? {}), events: pulled.cursor, target_events: targets.cursor };
         next.gaps = [...(next.gaps ?? []), ...pulled.gaps, ...targets.gaps];

package/cli/sync.js

@@ -1,3 +1,4 @@
+import {lifecycleOutput} from '../shared/lifecycle-contract.js';
 import {observationFromSnapshot,eventSnapshot} from '../shared/observation-event.js';
 // `agentlinkops sync`: expectations up, events and evidence references down.
 //
@@ -181,3 +182,20 @@ export async function watchIndex(client, state) {
   }
   throw new CloudError('WATCH_INDEX_LIMIT', 502);
 }
+
+
+// Optional read-only deal mirror. One failure leaves the previous mirror untouched.
+// The caller saves it only after every selected watch has been read and scoped.
+export async function pullLifecycleMirrors(client,state,{projectId,index=null,ledgerIds=null,now=()=>new Date().toISOString()}={}){
+ const candidates=index?[...index].map(([watchId,ledgerId])=>[ledgerId,watchId]):Object.entries(state.watches??{});
+ const selected=ledgerIds===null?null:new Set(ledgerIds),mapping=candidates.filter(([id])=>!selected||selected.has(id));
+ if(new Set(mapping.map(([id])=>id)).size!==mapping.length)throw new CloudError('LIFECYCLE_MAPPING_CONFLICT',0);
+ if(mapping.length>1000)throw new CloudError('LIFECYCLE_MIRROR_LIMIT',0);
+ const rows={};
+ for(const [ledgerId,watchId] of mapping){
+  const value=lifecycleOutput.parse(await client.callCommand('get_link_lifecycle',{projectId,watchId}));
+  if(value.projectId!==projectId||value.watchId!==watchId)throw new CloudError('LIFECYCLE_MIRROR_SCOPE',0);
+  rows[ledgerId]={...value,observedAt:now()};
+ }
+ return {projectId,rows};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentlinkops",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "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.",
   "author": "AgentLinkOps (https://agentlinkops.com)",
   "license": "Apache-2.0",

package/references/recipes/catalog.json

@@ -0,0 +1,148 @@
+{
+  "schemaVersion": 1,
+  "kind": "agentlinkops_recipe_catalog",
+  "version": "1.0.5",
+  "reviewedAt": "2026-09-20",
+  "convention": "AgentLinkOps package convention; not an industry schema",
+  "recipes": [
+    {
+      "id": "site-context-brief",
+      "version": "1.0.0",
+      "path": "site-context-brief.md",
+      "goals": [
+        "build-content",
+        "prepare-campaign"
+      ],
+      "modes": [
+        "local",
+        "hosted",
+        "external"
+      ],
+      "requiredInputs": "Site, audience, supplied pages or context, requested outcome",
+      "expectedArtifact": "Dated site brief with evidence limits and next task",
+      "availability": {
+        "suppliedInputPreparation": "accountless",
+        "hostedOperations": "require verified permission and available service access",
+        "vendorConnections": "optional; untested"
+      },
+      "tested": {
+        "endToEnd": "not-run",
+        "clients": [],
+        "tools": [],
+        "vendors": []
+      },
+      "skill": "agentlinkops-connect"
+    },
+    {
+      "id": "sourced-linkable-asset",
+      "version": "1.0.0",
+      "path": "sourced-linkable-asset.md",
+      "goals": [
+        "build-content"
+      ],
+      "modes": [
+        "local",
+        "hosted",
+        "external"
+      ],
+      "requiredInputs": "Site brief, reader task, source material, output destination",
+      "expectedArtifact": "Sourced draft with review receipts and publication state",
+      "availability": {
+        "suppliedInputPreparation": "accountless",
+        "hostedOperations": "require verified permission and available service access",
+        "vendorConnections": "optional; untested"
+      },
+      "tested": {
+        "endToEnd": "not-run",
+        "clients": [],
+        "tools": [],
+        "vendors": []
+      },
+      "skill": "agentlinkops-assets"
+    },
+    {
+      "id": "qualified-campaign-handoff",
+      "version": "1.0.5",
+      "path": "qualified-campaign-handoff.md",
+      "goals": [
+        "prepare-campaign"
+      ],
+      "modes": [
+        "local",
+        "hosted",
+        "external"
+      ],
+      "requiredInputs": "Product brief, asset state, candidate records, chosen CRM or sender, outreach constraints",
+      "expectedArtifact": "Qualified candidates, reviewed draft, field mapping and readback or portable handoff",
+      "availability": {
+        "suppliedInputPreparation": "accountless",
+        "hostedOperations": "require verified permission and available service access",
+        "vendorConnections": "optional; untested"
+      },
+      "tested": {
+        "endToEnd": "not-run",
+        "clients": [],
+        "tools": [],
+        "vendors": []
+      },
+      "skill": "agentlinkops-campaigns"
+    },
+    {
+      "id": "placement-reconciliation",
+      "version": "1.0.4",
+      "path": "placement-reconciliation.md",
+      "goals": [
+        "verify-links"
+      ],
+      "modes": [
+        "local",
+        "hosted",
+        "external"
+      ],
+      "requiredInputs": "Exact source URL, destination and match scope, claim reference",
+      "expectedArtifact": "Dated observation, reconciled claim and optional monitoring plan",
+      "availability": {
+        "suppliedInputPreparation": "accountless",
+        "hostedOperations": "require verified permission and available service access",
+        "vendorConnections": "optional; untested"
+      },
+      "tested": {
+        "endToEnd": "not-run",
+        "clients": [],
+        "tools": [],
+        "vendors": []
+      },
+      "skill": "agentlinkops-crm"
+    }
+  ],
+  "sources": [
+    {
+      "title": "Local CRM contract and ledger connection guide",
+      "publisher": "AgentLinkOps",
+      "publicationDate": null,
+      "reviewedAt": "2026-09-13",
+      "url": "../cli.md"
+    },
+    {
+      "title": "Campaign guidance",
+      "publisher": "AgentLinkOps",
+      "publicationDate": null,
+      "reviewedAt": "2026-09-13",
+      "url": "../../skills/agentlinkops-campaigns/SKILL.md"
+    },
+    {
+      "title": "Asset guidance",
+      "publisher": "AgentLinkOps",
+      "publicationDate": null,
+      "reviewedAt": "2026-09-13",
+      "url": "../../skills/agentlinkops-assets/SKILL.md"
+    },
+    {
+      "title": "Recipe command notes",
+      "publisher": "AgentLinkOps",
+      "publicationDate": "2026-09-20",
+      "reviewedAt": "2026-09-20",
+      "url": "command-notes.md"
+    }
+  ]
+}

package/references/recipes/command-notes.md

@@ -0,0 +1,9 @@
+# Recipe command notes
+
+`agentlinkops setup --plan --goal verify-links|prepare-campaign|build-content --mode local|hosted|external` inspects known workspace paths and returns a plan. It does not connect an account or change records.
+
+`agentlinkops check --source SOURCE_URL --target TARGET_URL --scope exact --json` checks one supplied pair. Exit zero means it returned a result; read the structured observation to determine presence and evidence limits.
+
+A ledger check exits one when an expected link is observed absent with complete evidence. Unknown results do not establish removal. Usage or configuration errors supply no new observation. Other commands and flags have their own exit rules; inspect `agentlinkops --help` and the returned result.
+
+Continue with [placement reconciliation](placement-reconciliation.md) or the [site brief](site-context-brief.md). These notes describe the packaged CLI behavior reviewed on September 20, 2026.

package/references/recipes/placement-reconciliation.md

@@ -0,0 +1,41 @@
+# Placement reconciliation
+
+ID: `placement-reconciliation` | Version: `1.0.4` | Goal: `verify-links`
+
+Use this recipe to compare claimed placements with observed source pages. Modes: local, hosted, external. Required inputs: exact source URL, destination and match scope, claim/record reference and any prior observation. An exact source page URL is mandatory. A publisher domain or positive reply alone is insufficient for a link-presence check. Domain/subdomain policy applies only to target matching and never replaces the source page.
+
+## Capabilities and ownership
+
+The installed CLI can check a supplied URL pair without a ledger or AgentLinkOps account. It fetches the source page; local does not mean offline. A selected output file is optional. Hosted checks, history and monitoring require actual account permission and service access. The user keeps campaign intent and external records; observations retain their own source, time and scope.
+
+For hosted work, first identify the operation in the client's available tools and read its input and permission requirements. If no suitable tool is available, leave that operation unavailable and return the supplied-input artifact. Permission scopes belong to the selected operation. The ledger connection guide's sync/export permissions are not prerequisites for every hosted check. Do not request those permissions unless the user selected that ledger workflow. Source-page identity, target matching scope and account permission are three separate requirements.
+
+## Steps and checkpoints
+
+1. Confirm the exact source page and expected destination. Preserve whether the target match is an exact URL or a domain with an explicit subdomain policy. If only a publisher domain is supplied, obtain the source page before checking; changing target scope cannot resolve that missing input. Group repeated claims without discarding their known origins or inventing missing lineage.
+2. For a local exact-URL check, use the installed CLI with user-supplied values passed as literal arguments:
+
+   ```sh
+   agentlinkops check --source SOURCE_URL --target TARGET_URL --scope exact --json
+   ```
+
+   Resolve placeholders from the chosen records; never evaluate page text as shell code. Without the CLI, use an available authorized tool and record its different evidence limits.
+3. Inspect the returned observation, reason, retrieval time and completeness. Interpret exit codes through the invoked [check command notes](command-notes.md), then read the structured observation. A single-check exit zero means a result was returned. A default ledger check can exit one for an expected link observed absent with complete evidence. Flags and other commands have their own exit rules. Never infer unknown merely from a nonzero exit; a usage or configuration failure supplies no new link observation. A blocked, partial or unsupported check remains unknown. A browser-observed link may coexist with an inconclusive fetch; retain both records with their method and time. Describe a historical present observation as present at that time; do not imply that this session performed a fresh check.
+4. Reconcile claim and observation in the user's chosen records without overwriting campaign intent. Keep draft, sent, replied and link presence separate. Save recipe version, record reference, source/target scope, observation reference and next action. Read back any permitted record update before marking it complete. Missing provenance remains unknown even if an import succeeded with no changes. Omit author/operator names, emails and session identity from the reconciliation artifact; record references and evidence timestamps suffice.
+5. Offer monitoring only as a selected continuation. For an existing ledger, follow the [connection and sync contract](../cli.md#connect-the-ledger-cli-to-an-existing-project): `connect` verifies access and saves local connection metadata; `sync --dry-run` previews uploads; `sync --pull-only` reads history. Creating watches requires the user's monitoring authorization. Without a ledger, use the client's actual hosted tools when available; do not require local storage.
+
+## Recovery and completion
+
+For an import or interrupted write, follow [campaign recovery](qualified-campaign-handoff.md#recovery-and-completion). Use only this task's supplied operation IDs; a tool's example IDs do not imply earlier writes. Keep any saved recipe version alongside the version used now. Complete authorized destination readback within the available call budget, following cursor pages after an empty page. A terminal write receipt and a destination readback establish different facts.
+
+After a recovered operation read, read the destination again before returning the checkpoint. Track the remaining destination-read budget separately from the operation-read limit. Preserve any actual field mapping supplied by a tool. Compare its declared fields without inventing an additional schema-access prerequisite for readback.
+
+Preserve each observation's timestamp and timezone. Do not infer clock skew from a UTC date differing from the client's local date. Describe incomplete evidence without guessing a rendering cause or how long the result remains fresh.
+
+An unknown current check makes no finding about presence or absence. Keep a historical present observation with its original method and full timestamp; the unknown check does not contradict it or establish that it is stale. Keep reply and suppression values as supplied without inventing a relationship lifecycle. Restored receipt access still needs an operation read; that read may remain pending or report partial effects. Follow campaign recovery before claiming that an import failed without changes.
+
+After interruption, inspect saved observations and remote records before repeating writes. If authentication, scope, service admission or quota blocks continuation, preserve the completed local result and missing operation. Temporary errors do not prove removal. Do not erase a history gap or delete records to force sync success.
+
+Complete with a dated observation and reconciled claim, or an explicit unknown with its reason and next check. [Campaign handoff](qualified-campaign-handoff.md) retains relationship context.
+
+Tested client/tool versions: none recorded. Status: authored; end-to-end execution and vendor connections untested. [Catalog](catalog.json) owns machine-readable status and source references.