agentlinkops 0.6.11 → 0.6.16

package/cli/fleet.js

@@ -6,54 +6,62 @@
 // and a summary that deduplicated them would silently pick one. So every number below is
 // per project, the only cross-project arithmetic is a sum of counts, and the output says so.
 //
-// "Earned" follows the ledger contract, not a status column: an entry is earned when its
-// latest OBSERVATION says present. A project with no observation file has earned nothing and
-// is reported as never checked rather than as zero links.
+// "Earned" follows known conclusive presence; a later inconclusive attempt is disclosed
+// separately. Activity is supplied explicitly per project, never discovered in another repo.
 import { readLedger } from './ledger.js';
-import { readObservations, latestByEntry } from './mirror.js';
+import { readObservations } from './mirror.js';
+import { readState } from './state.js';
+import { projectPlacements } from './placement-projection.js';
 
 const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 
 /** One project's row. Everything is computed inside the project; nothing crosses the boundary. */
-export async function fleetProject(name, ledgerPath, observationsPath) {
+export async function fleetProject(name, ledgerPath, observationsPath, statePath = null) {
   const ledger = await readLedger(ledgerPath);
   if (ledger.missing) { const error = new Error(`no ledger at ${ledgerPath}`); error.code = 'NO_LEDGER'; throw error; }
   const byIntent = { wanted: 0, expected: 0, retired: 0 };
   for (const entry of ledger.entries) byIntent[entry.intent] = (byIntent[entry.intent] ?? 0) + 1;
 
   const { rows } = observationsPath ? await readObservations(observationsPath) : { rows: [] };
-  const latest = latestByEntry(rows);
-  let earned = 0, observed = 0;
-  for (const [id, row] of latest) {
-    if (!ledger.entries.some(entry => entry.id === id)) continue; // observations from another ledger's ids
-    observed++;
-    if (row.state === 'present') earned++;
-  }
-  const lastCheck = rows.length ? rows.map(row => row.checked_at).sort().at(-1) : null;
+  const state = statePath ? await readState(statePath) : null;
+  const eligible = ledger.entries.filter(entry => entry.intent !== 'retired');
+  const projected = projectPlacements(eligible, rows, { state });
+  const observed = projected.filter(item => item.latest_attempt).length;
+  const earned = projected.filter(item => item.current_state === 'present').length;
+  const newest = values => values.filter(Boolean).sort((a, b) => Date.parse(a) - Date.parse(b)).at(-1) ?? null;
   return {
     project: name, ledger: ledgerPath,
     entries: ledger.entries.length, ...byIntent,
     problems: ledger.problems.length,
     observed_entries: observed, earned,
-    never_checked: ledger.entries.filter(entry => entry.intent !== 'retired').length - observed,
-    last_observation: lastCheck,
+    never_checked: eligible.length - observed,
+    last_observation: newest(projected.map(item => item.evidence_observed_at)),
+    last_attempt_at: newest(projected.map(item => item.latest_attempt?.checked_at)),
+    last_success_at: newest(projected.map(item => item.last_successful_observation?.checked_at)),
+    last_link_verification_at: newest(projected.map(item => item.last_link_verification?.checked_at)),
+    uncertain_entries: projected.filter(item => item.uncertain).length,
+    activity_available: projected.some(item => item.activity_available),
+    activity_entries: projected.filter(item => item.activity_available).length,
+    coverage: { denominator: 'non_retired_ledger_entries', eligible_entries: eligible.length,
+      identity_unmatched_entries: projected.filter(item => item.identity_status === 'not_matched').length,
+      activity_input: statePath ? 'explicit_state_file' : 'not_supplied' },
     // Due volume, the same arithmetic the dogfood records use to price a fleet.
     implied_weekly_checks: byIntent.wanted + byIntent.expected * 7,
   };
 }
 
 /** Summons the fleet. Same numbers per project, one sum of counts, no merged intent. */
-export async function fleetSummary(projects, { observationsOf = {} } = {}) {
+export async function fleetSummary(projects, { observationsOf = {}, statesOf = {} } = {}) {
   const rows = [];
-  for (const { name, ledger } of projects) rows.push(await fleetProject(name, ledger, observationsOf[name] ?? null));
+  for (const { name, ledger } of projects) rows.push(await fleetProject(name, ledger, observationsOf[name] ?? null, statesOf[name] ?? null));
   const totals = rows.reduce((acc, row) => {
-    for (const key of ['entries', 'wanted', 'expected', 'retired', 'earned', 'observed_entries', 'never_checked', 'implied_weekly_checks']) {
+    for (const key of ['entries', 'wanted', 'expected', 'retired', 'earned', 'observed_entries', 'never_checked', 'uncertain_entries', 'activity_entries', 'implied_weekly_checks']) {
       acc[key] = (acc[key] ?? 0) + row[key];
     }
     return acc;
   }, {});
   return {
-    v: 1, projects: rows, totals,
+    v: 2, projects: rows, totals,
     // The sum answers "how big is the operation". It is not a merged view: the same platform
     // counted in two projects is two intents, and only a human can say which one they meant.
     intent_merged_across_repos: false,
@@ -75,6 +83,9 @@ export function renderFleet(summary, out = console.log) {
     + `${String(t.never_checked).padStart(13)}  (sum of counts)`);
   out('');
   out(`implied weekly check volume across the fleet: ${t.implied_weekly_checks}`);
+  for (const row of summary.projects) {
+    out(`${row.project}: latest attempt ${row.last_attempt_at ?? 'not recorded'}; last conclusive check ${row.last_success_at ?? 'not recorded'}; last link verification ${row.last_link_verification_at ?? 'not recorded'}; activity ${row.activity_available ? `${row.activity_entries} entr(ies)` : 'not available'}; uncertain ${row.uncertain_entries}`);
+  }
   if (summary.projects.some(row => row.problems)) {
     out(`ledger problems: ${summary.projects.map(row => `${row.project}=${row.problems}`).filter(s => !s.endsWith('=0')).join(', ')}`);
   }

package/cli/import.js

@@ -54,6 +54,7 @@ export async function readImport(path, {
 
   const resolved = resolveMapping(table.header, { supplier, overrides: map, targetProvided: Boolean(target) });
   if (resolved.error) return { error: resolved.error, header: table.header };
+  const targetExpectation = supplier === 'google_search_console' && !resolved.mapping.target && Boolean(target);
 
   const unreadable = table.records.filter(record => record.error).map(record => ({ row: record.line, reason: record.error }));
   const readable = table.records.filter(record => record.values);
@@ -63,7 +64,12 @@ export async function readImport(path, {
   // means. Nothing is inferred — without --target the resolver above refuses the file.
   if (!resolved.mapping.target) {
     const targetUrl = targetKind === 'domain' ? `https://${target}/` : target;
-    for (const row of rows) row.target_url = targetUrl;
+    for (const row of rows) {
+      row.target_url = targetUrl;
+      // This is the caller's target expectation, not a destination observed by Google.
+      // The verifier can use the saved run scope without asserting an exact root-page link.
+      if (targetExpectation) row.target_basis = 'user_supplied_target_expectation';
+    }
   }
 
   const targetUrl = targetKind === 'domain' ? `https://${target}/` : target;

package/cli/key-store.js

@@ -0,0 +1,115 @@
+// Where `agentlinkops connect` keeps the API key a person pastes, so cloud commands work in any
+// folder without environment variables. Never inside a repository:
+//
+//   macOS  the login Keychain, through /usr/bin/security. `security -i` takes the key on stdin,
+//          so it never appears in a process listing.
+//   Linux  ~/.agentlinkops/keys/, one file per cloud origin, mode 600 in a mode 700 directory
+//          owned by the person; anything looser is ignored rather than trusted.
+//   other  nothing is saved; AGENTLINKOPS_API_KEY keeps working everywhere.
+//
+// One key per cloud origin. Reads are synchronous because cloudConnection() is.
+import { execFile, execFileSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { lstatSync, readFileSync } from 'node:fs';
+import * as fs from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { ConfigError } from './config.js';
+
+export const API_KEY_PATTERN = /^lt_[0-9a-f]{64}$/;
+// main() attaches the reader to the environment object it hands every command, under this
+// symbol: it never reaches a child process, a JSON dump or a test that passes its own env.
+export const STORED_KEY = Symbol.for('agentlinkops.storedKey');
+
+const SECURITY = '/usr/bin/security';
+const SERVICE = 'agentlinkops-cli';
+// An origin is a Keychain account name and a file-name input: canonical https only, no spaces
+// or quotes, so it can sit unquoted in a `security -i` command line.
+const canonical = origin => {
+  try { const url = new URL(origin); return url.protocol === 'https:' && url.origin === origin && !/[\s"'\\]/.test(origin); }
+  catch { return false; }
+};
+
+const runSync = (file, args) => execFileSync(file, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 });
+const run = (file, args, input) => new Promise((resolve, reject) => {
+  const child = execFile(file, args, { encoding: 'utf8', timeout: 10000 }, (error, stdout) => error ? reject(error) : resolve(stdout));
+  child.stdin.end(input);
+});
+
+function keychainStore({ exec = runSync, execInput = run }) {
+  const store = {
+    where: 'your macOS Keychain',
+    readSync(origin) {
+      if (!canonical(origin)) return null;
+      try {
+        const key = exec(SECURITY, ['find-generic-password', '-s', SERVICE, '-a', origin, '-w']).trim();
+        return API_KEY_PATTERN.test(key) ? key : null;
+      } catch { return null; } // 44: no such item. Anything else reads as no saved key.
+    },
+    async save(origin, key) {
+      if (!canonical(origin) || !API_KEY_PATTERN.test(key)) throw new ConfigError('Only a complete API key for an https origin can be saved.');
+      await execInput(SECURITY, ['-i'], `add-generic-password -U -s ${SERVICE} -a ${origin} -w ${key}\n`).catch(() => {});
+      // `security -i` reports per-command failures on its own output, so read the key back.
+      if (store.readSync(origin) !== key) throw new ConfigError('The key could not be saved in your macOS Keychain. Set AGENTLINKOPS_API_KEY instead.');
+    },
+    async remove(origin) {
+      if (!canonical(origin)) return false;
+      try { exec(SECURITY, ['delete-generic-password', '-s', SERVICE, '-a', origin]); return true; } catch { return false; }
+    },
+  };
+  return store;
+}
+
+function fileStore({ home, uid = process.getuid?.() }) {
+  const dir = join(home, '.agentlinkops', 'keys');
+  const fileFor = origin => join(dir, `${createHash('sha256').update(origin).digest('hex').slice(0, 32)}.json`);
+  const own = info => uid !== undefined && info.uid === uid;
+  const privateDir = info => info.isDirectory() && own(info) && (info.mode & 0o777) === 0o700;
+  const privateFile = info => info.isFile() && info.nlink === 1 && own(info) && (info.mode & 0o777) === 0o600;
+  return {
+    where: '~/.agentlinkops/keys (readable only by you)',
+    readSync(origin) {
+      if (!canonical(origin)) return null;
+      try {
+        if (!privateDir(lstatSync(dir)) || !privateFile(lstatSync(fileFor(origin)))) return null;
+        const record = JSON.parse(readFileSync(fileFor(origin), 'utf8'));
+        return record?.origin === origin && API_KEY_PATTERN.test(record.key) ? record.key : null;
+      } catch { return null; }
+    },
+    async save(origin, key) {
+      if (!canonical(origin) || !API_KEY_PATTERN.test(key)) throw new ConfigError('Only a complete API key for an https origin can be saved.');
+      for (const path of [join(home, '.agentlinkops'), dir]) {
+        try { await fs.mkdir(path, { mode: 0o700 }); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+      }
+      if (!privateDir(await fs.lstat(dir))) throw new ConfigError(`${dir} must be a directory only you can open (mode 700). Fix it, or set AGENTLINKOPS_API_KEY instead.`);
+      const path = fileFor(origin), temporary = `${path}.${randomBytes(8).toString('hex')}.tmp`;
+      try {
+        await fs.writeFile(temporary, `${JSON.stringify({ origin, key })}\n`, { flag: 'wx', mode: 0o600 });
+        await fs.rename(temporary, path);
+      } finally { await fs.unlink(temporary).catch(() => {}); }
+    },
+    async remove(origin) {
+      if (!canonical(origin)) return false;
+      try { await fs.unlink(fileFor(origin)); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+    },
+  };
+}
+
+const unsupported = {
+  where: null,
+  readSync: () => null,
+  async save() { throw new ConfigError('This platform has no supported place to save a key yet. Set AGENTLINKOPS_API_KEY instead.'); },
+  async remove() { return false; },
+};
+
+export function createKeyStore({ platform = process.platform, home = homedir(), exec, execInput, uid } = {}) {
+  if (platform === 'darwin') return keychainStore({ exec, execInput });
+  if (platform === 'linux' && typeof home === 'string' && isAbsolute(home)) return fileStore({ home, uid });
+  return unsupported;
+}
+
+/** The environment a command sees, plus a reader for keys saved by `agentlinkops connect`. */
+export function withStoredKeys(env, store) {
+  if (!store) return env;
+  return { ...env, [STORED_KEY]: origin => { const key = store.readSync(origin); return key ? { key, where: store.where } : null; } };
+}

package/cli/ledger.js

@@ -214,6 +214,7 @@ export function toWatchInput(entry) {
   // caller can say so rather than discovering it when a reference comes back short.
   const reference = entry.ref ? `${entry.id} ${entry.ref}` : entry.id;
   return {
+    intent: ({wanted:'prospect',expected:'earned',retired:'retired'})[entry.intent],
     sourceUrl: entry.source, targetUrl: entry.target, targetScope: entry.scope,
     cadenceSeconds: cadenceSeconds(entry.cadence ?? DEFAULT_CADENCE[entry.intent] ?? 'daily'),
     expectedAnchor: entry.expect?.anchor ?? null,

package/cli/local-result.js

@@ -15,11 +15,26 @@ export const LOCAL_RESULT_SCHEMA = 'agentlinkops.local-check.v1';
 
 const timestamp = z.string().refine(value => Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value);
 const strings = z.array(z.string());
+const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+const capturePin = z.string().min(1).max(128).regex(/^[^\x00-\x20\x7f]+$/u);
+const bodyDiagnosticSchema = z.strictObject({ version: z.literal(1), bytes: z.number().int().min(0).max(64 * 1024),
+  complete: z.boolean(), truncated: z.boolean(), sha256: digest, looksLikeHtml: z.boolean() });
+const googlebotSchema = z.strictObject({ productToken: z.literal('Googlebot'), allowed: z.boolean().nullable(),
+  reason: z.string().nullable(), matchedRule: z.string().nullable(), crawlDelaySeconds: z.number().finite().min(0).nullable() });
+const captureSchema = z.strictObject({ version: z.literal(1), representation: z.literal('raw_html'),
+  requestedUrl: z.string(), finalUrl: z.string(), httpStatus: z.number().int().min(100).max(599), acquiredAt: timestamp,
+  body: z.strictObject({ complete: z.literal(true), truncated: z.literal(false), bytes: z.number().int().min(0).max(2 * 1024 * 1024),
+    sha256: digest, decodedSha256: digest, charset: z.string().max(64).nullable().optional() }),
+  transport: z.strictObject({ id: capturePin, version: capturePin, qualified: z.literal(true) }),
+  coverage: z.strictObject({ mainDocument: z.literal(true), iframes: z.literal(false), shadowRoots: z.literal(false) }) });
 const redirectSchema = z.strictObject({ from: z.string(), to: z.string(), status: z.number().int() });
 const robotsSchema = z.strictObject({ allowed: z.boolean().nullable(), reason: z.string().nullable(),
   matchedRule: z.string().nullable(), crawlDelaySeconds: z.number().nullable(), fetched: z.string().nullable(),
   sourceUrl: z.string().optional(), robotsUrl: z.string().optional(), httpStatus: z.number().int().nullable().optional(),
-  productToken: z.string().optional(), redirects: z.array(redirectSchema).max(5).optional(), retryAfterSeconds: z.number().optional() });
+  productToken: z.string().optional(), redirects: z.array(redirectSchema).max(5).optional(), retryAfterSeconds: z.number().finite().min(0).max(86400).optional(),
+  googlebot: googlebotSchema.optional(), decisionReason: z.string().nullable().optional(),
+  policy: z.literal('customer_supplied_monitor').optional(), fetchAuthorized: z.boolean().optional(), overrideUsed: z.literal(false).optional(),
+  bodyDiagnostic: bodyDiagnosticSchema.optional() });
 const readinessSchema = z.strictObject({ requiresRender: z.boolean(), reason: z.string().nullable(), possibleLoginWall: z.boolean(),
   hasVisiblePassword: z.boolean().optional(), targetInScript: z.boolean().optional(), emptyAppRoot: z.boolean().optional(), emptyProfileRoot: z.boolean().optional() });
 const occurrenceSchema = z.strictObject({ href: z.string(), targetUrl: z.string(), anchor: z.string(), rel: strings,
@@ -28,15 +43,18 @@ const observationSchema = z.strictObject({
   state: z.enum(['present','absent','unknown','source_unavailable']), reason: z.string(), sourceUrl: z.string(), finalUrl: z.string(), targetUrl: z.string(),
   targetScope: z.enum(['exact','domain','subdomain','path']), httpStatus: z.number().int().nullable(), checkedAt: timestamp,
   occurrences: z.array(occurrenceSchema).max(1000),
-  directives: z.strictObject({ meta: z.array(z.strictObject({ name: z.string(), content: z.string() })), xRobotsTag: strings, noindex: z.boolean(), nofollow: z.boolean(), indexingStatus: z.string() }),
+  directives: z.strictObject({ meta: z.array(z.strictObject({ name: z.string(), content: z.string() })), xRobotsTag: strings, noindex: z.boolean(), nofollow: z.boolean(), indexingStatus: z.string(),
+    googlebot: z.strictObject({ noindex: z.boolean(), nofollow: z.boolean() }).optional() }),
   redirects: z.array(redirectSchema),
   evidence: z.strictObject({ method: z.string(), checkerVersion: z.string(), complete: z.boolean(), fetchedAt: timestamp.nullable(),
     bytes: z.number().optional(), contentType: z.string().nullable().optional(), etag: z.string().nullable().optional(), lastModified: z.string().nullable().optional(),
-    baseUrl: z.string().optional(), rendered: z.boolean().optional(), sha256: z.string().optional(), parseErrors: strings.optional(),
-    readiness: readinessSchema.optional(), renderEligibility: z.enum(['required', 'comparison']).optional() }),
+    baseUrl: z.string().optional(), rendered: z.literal(false).optional(), sha256: digest.optional(), decodedSha256: digest.optional(),
+    capture: captureSchema.nullable().optional(), parseErrors: strings.optional(),
+    readiness: readinessSchema.optional(), renderEligibility: z.enum(['required', 'comparison']).optional(),
+    renderAttempt: z.strictObject({ attempted: z.literal(false), reason: z.literal('render_not_configured') }).optional() }),
   robots: robotsSchema.optional(), robotsHistory: z.array(robotsSchema).max(6).optional(),
   sourceResponse: z.strictObject({ url: z.string(), httpStatus: z.number().int(), contentType: z.string().max(128).nullable(),
-    retryAfterSeconds: z.number().nullable(), challenge: z.boolean() }).optional(),
+    retryAfterSeconds: z.number().nullable(), challenge: z.boolean(), bodyDiagnostic: bodyDiagnosticSchema.optional() }).optional(),
   expectations: z.strictObject({ expectedAnchor: z.string().nullable(), expectedRel: strings.nullable(), anchorMatches: z.boolean().nullable(), relMatches: z.boolean().nullable(), satisfied: z.boolean() }).optional(),
   linkSignature: z.string().optional(), warnings: strings.optional(), retryAfterSeconds: z.number().optional(),
 });
@@ -88,11 +106,28 @@ export function validateLocalResult(result) {
   const rejectBytes = value => {
     if (!value || typeof value !== 'object') return;
     for (const [key, child] of Object.entries(value)) {
-      if (['html','body','headers'].includes(key.toLowerCase())) throw new Error('portable observations cannot contain raw HTML/body/headers');
+      if (['html','body','headers'].includes(key.toLowerCase())
+        && !(key === 'body' && value === observation.evidence?.capture)) throw new Error('portable observations cannot contain raw HTML/body/headers');
       rejectBytes(child);
     }
   };
   rejectBytes(observation);
+  const capture = observation.evidence.capture;
+  if (capture) {
+    if (capture.requestedUrl !== input.source || capture.finalUrl !== observation.finalUrl
+      || !validatePublicUrl(capture.finalUrl).valid || capture.httpStatus !== observation.httpStatus
+      || capture.acquiredAt !== observation.evidence.fetchedAt
+      || capture.body.bytes !== observation.evidence.bytes || capture.body.sha256 !== observation.evidence.sha256
+      || capture.body.decodedSha256 !== observation.evidence.decodedSha256
+      || observation.evidence.method !== 'http_html') throw new Error('portable capture does not match its observation');
+    if (capture.body.charset != null) {
+      try { new TextDecoder(capture.body.charset, { fatal: true }); }
+      catch { throw new Error('invalid portable capture charset'); }
+    }
+  }
+  if (observation.evidence.renderAttempt && (observation.state !== 'unknown' || observation.evidence.complete !== false
+    || !['possible_render_required', 'navigation_requires_browser'].includes(observation.reason)
+    || observation.evidence.renderEligibility !== 'required')) throw new Error('invalid portable refused-render observation');
   if (observation.occurrences.some(item => !item || typeof item.targetUrl !== 'string' || !Array.isArray(item.rel)
     || !matchesTarget(item.targetUrl, input.target, input.scope))) throw new Error('invalid portable occurrence');
   if (observation.state === 'present' && (!observation.evidence.complete || !observation.occurrences.length)) throw new Error('present requires complete matching occurrences');

package/cli/main.js

@@ -1,5 +1,8 @@
+import {projectPlacements} from './placement-projection.js';
+import {chronologyMain} from './chronology.js';
 import { acquireSyncLock } from './sync-lock.js';
 import {lifecycleMain} from './lifecycle.js';
+import {campaignMain,CAMPAIGN_CLI_HELP} from './campaign-bridge.js';
 import {admissionMain} from './admission.js';
 import { commandsMain } from './commands.js';
 import { disavowMain } from './disavow.js';
@@ -21,8 +24,10 @@ import { checkToFile, adoptLocalResult } from './local-result.js';
 import { disagreements, transitions } from './status.js';
 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 { createClient, CloudError, CLI_VERSION } from './client.js';
+import { cloudConnection, connectKey, connectMain, keySetup } from './connection.js';
+import { createKeyStore, withStoredKeys } from './key-store.js';
+import { askSecret } from './prompt.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';
@@ -44,6 +49,8 @@ import { citationMain } from './citation.js';
 
 const USAGE = `agentlinkops — a backlink ledger that lives in your repository
 
+  agentlinkops --version              print the installed CLI version
+
   agentlinkops skill [--url|--list [--json]|NAME]  read the agent reference or a named skill
                                             before the first AgentLinkOps call
   agentlinkops init                   create .agentlinkops/ here
@@ -52,9 +59,12 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
                 [--mode local|hosted|external]  read-only setup plan; no account required
   agentlinkops add --source URL --target URL [--intent wanted|expected] [--scope …]
                 [--anchor TEXT] [--rel a,b] [--ref TEXT] [--tag t --tag t] [--note TEXT]
+  agentlinkops chronology pull --watch-id ID [--limit N] [--cursor TOKEN] [--all] [--out FILE]
+  agentlinkops chronology export --pages FILE [--submissions FILE] [--out FILE]
   agentlinkops index pull --watch-id ID [--limit N] [--before ID]
+  agentlinkops campaign plan|apply|reconcile|rollback|pull-plan|pull-apply|pull-rollback|outcomes-plan|outcomes-apply
+                                            preview and reconcile portable campaign records; no sending or automatic checks
   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]
@@ -63,7 +73,7 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
   agentlinkops import FILE --target DOMAIN [--from SUPPLIER] [--map source=COL,target=COL]
                 [--exact-url] [--no-subdomains] [--generated-at ISO] [--json]
   agentlinkops adopt CRM.sqlite [--scope exact|domain] [--write]
-  agentlinkops fleet --project NAME=LEDGER [--project …] [--observations-of NAME=FILE] [--json]
+  agentlinkops fleet --project NAME=LEDGER [--project …] [--observations-of NAME=FILE] [--state-of NAME=FILE] [--json]
   agentlinkops platforms [HOST] [--observations FILE]… [--benchmark FILE]… [--seed FILE]…
                 [--for-candidates FILE] [--json]
   agentlinkops context COMMAND…               first-party search context and site profile
@@ -78,7 +88,9 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
                                             .agentlinkops/citations/; live engines need
                                             engine-specific setup; the mock engine makes no paid calls
   agentlinkops receive --body FILE --headers FILE   signed notification; authenticated pull
-  agentlinkops connect --workspace ID --project-id ID [--origin URL] [--selection FILE] [--oauth --issuer URL --client-id ID [--credential-ref REF]]
+  agentlinkops connect [--project-id ID] [--workspace ID] [--origin URL] [--selection FILE] [--oauth --issuer URL --client-id ID [--credential-ref REF]]
+                                            paste an API key once; it is saved outside the
+                                            repository and the key names its workspace
   agentlinkops tools [TOOLSET] [--json] [--refresh]   cloud commands by toolset (offline snapshot;
                                             --refresh reads the live catalog)
   agentlinkops describe NAME [--examples] [--output-schema] [--json]  one command's exact schema
@@ -87,7 +99,8 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
   agentlinkops agent setup [--client ID ...] [--scope project|user] [--origin URL] [--dry-run]
                                             core connection/reference and the right MCP view;
                                             optional --skill ID ... / --recipe ID ... / --all-skills;
-                                            stores no credential; preserves customer instructions
+                                            stores no credential unless you paste a CLI key
+                                            when asked; preserves customer instructions
   agentlinkops agent status                 what is installed where
   agentlinkops agent remove [--skill ID ...] [--recipe ID ...] [--scope project|user] [--apply] [--json]
   agentlinkops agent recover [--scope project|user] [--apply] [--json]
@@ -100,7 +113,7 @@ const USAGE = `agentlinkops — a backlink ledger that lives in your repository
   agentlinkops adopt-result FILE [--intent wanted|expected]  save result to local ledger
   agentlinkops receipt add --file CLAIM.json   project.site declares public site hosts
   agentlinkops receipt history [--performance FILE.json]  claims, history and optional dated context
-  agentlinkops status [--json]
+  agentlinkops status [--all] [--json]
   agentlinkops diff [--json]
   agentlinkops report [--out FILE] [--title T] [--brand B] [--as-of ISO]
                 [--include-notes] [--include-retired] [--digest-only] [--json]
@@ -122,7 +135,25 @@ evidence · 2 usage, configuration or ledger error. Unknown is nonfailing by def
 Names: \`linktrail\` still runs this CLI, LINKTRAIL_* variables are still read, and an existing
 .linktrail/ directory is still used, each with a one-line notice, until the DP-0029 cutover.`;
 
-const parseArgs = argv => parseArguments(argv,["tag", "project", "observations-of", "observations", "benchmark", "seed"],{tag:[]});
+// After `agent setup` on a terminal: the CLI half, so the folder's agent can also run
+// `agentlinkops call`. Optional (Enter skips), and setup has already succeeded either way.
+async function connectCliAfterSetup(origin, { env, ask, keyStore, fetchImpl, out }) {
+  let connection = null;
+  try { connection = cloudConnection({ cloud: { origin } }, env); } catch { /* Disagreeing variables: connect reports them. */ }
+  out('');
+  if (connection?.token) { out(`The agentlinkops CLI can use this account too (key in ${connection.tokenSource}).`); return; }
+  try {
+    const key = await connectKey({ origin, ask, keyStore, fetchImpl, out,
+      prompt: `To use the agentlinkops CLI as well, paste an API key from ${origin}/#/access (Create API key), or press Enter to skip: ` });
+    out(key
+      ? `The CLI is connected to ${key.account.workspace.name || 'your workspace'}. Try: agentlinkops call list_tasks`
+      : 'Skipped. Run `npx -y agentlinkops connect` when you want the CLI.');
+  } catch (error) {
+    out(`The CLI wasn't connected: ${error.serverMessage ?? error.message}. Run \`npx -y agentlinkops connect\` to try again.`);
+  }
+}
+
+const parseArgs = argv => parseArguments(argv,["tag", "project", "observations-of", "state-of", "observations", "benchmark", "seed"],{tag:[]});
 
 const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 
@@ -135,7 +166,16 @@ function reportProblems(problems, what, out) {
   if (problems.length > 20) out(`  … and ${problems.length - 20} more`);
 }
 
-export async function main(argv = process.argv.slice(2), { cwd = process.cwd(), out = console.log, err = console.error, env = process.env, fetchImpl = globalThis.fetch, afterHistoryPersisted, afterStatePersisted } = {}) {
+export async function main(argv = process.argv.slice(2), options) {
+  // The executables call main() with no options, the one caller that reads the person's saved
+  // key and asks on their terminal. Every other caller passes options and gets neither.
+  const executable = options === undefined;
+  const { cwd = process.cwd(), out = console.log, err = console.error, fetchImpl = globalThis.fetch, localFetchImpl = null, afterHistoryPersisted, afterStatePersisted, signal,
+    keyStore = executable ? createKeyStore() : null,
+    ask = executable && process.stdin.isTTY === true && process.stderr.isTTY === true ? askSecret : null } = options ?? {};
+  if (argv.length === 1 && argv[0] === '--version') { out(CLI_VERSION); return 0; }
+  if (argv[0] === 'campaign' && argv.length===2 && ['--help','help'].includes(argv[1])) { out(CAMPAIGN_CLI_HELP); return 0; }
+  const env = withStoredKeys(options?.env ?? process.env, keyStore);
   if (argv[0] === 'gsc-links') return await gscLinksMain(argv, { cwd, out });
   // Citation watches keep their own files under .agentlinkops/citations/ and never
   // touch the link ledger, so they dispatch before its requirement like context does.
@@ -151,24 +191,27 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
   try {
     if (args['recover-cursors'] !== undefined && (command !== 'sync' || args['recover-cursors'] !== true || args['pull-only'] !== true || args['push-only']))
       throw new ConfigError('Cursor recovery requires agentlinkops sync --pull-only --recover-cursors; it performs no remote writes.');
+    if (command === 'campaign') return await campaignMain(args,{cwd,env,fetchImpl,out});
     if (command === 'lifecycle') return await lifecycleMain(args,{cwd,env,fetchImpl,out,err});
     if (command === 'admission') { const config=await loadConfig({cwd}); return await admissionMain(argv.slice(1),{client:createClient({...cloudConnection(config,env),fetchImpl}),out,err}); }
     if (command === 'disavow') return await disavowMain(args,{cwd,env,fetchImpl,out});
+    if (command === 'chronology') return await chronologyMain(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 === 'schema' || command === 'call') return await commandsMain(argv, { cwd, out, err, env, fetchImpl });
     if (command === 'skill') return await skillMain(argv, { out });
-    if (command === 'agent') return await agentMain(argv, { cwd, out, err });
+    if (command === 'agent') return await agentMain(argv, { cwd, out, err, env, connectCli: ask && keyStore ? origin => connectCliAfterSetup(origin, { env, ask, keyStore, fetchImpl, out }) : null });
     if (command === 'connect') {
-      if (args._.length !== 1 || args.tag.length || Object.keys(args).some(key => !['_', 'tag', 'origin', 'workspace', 'project-id', 'selection', 'oauth', 'issuer', 'client-id', 'credential-ref'].includes(key))) throw new ConfigError('connect --workspace ID --project-id ID [--origin URL] [--selection FILE] [--oauth --issuer URL --client-id ID [--credential-ref REF]]');
-      return await connectMain(args, { cwd, out, env, fetchImpl });
+      if (args._.length !== 1 || args.tag.length || Object.keys(args).some(key => !['_', 'tag', 'origin', 'workspace', 'project-id', 'selection', 'oauth', 'issuer', 'client-id', 'credential-ref'].includes(key))) throw new ConfigError('connect [--project-id ID] [--workspace ID] [--origin URL] [--selection FILE] [--oauth --issuer URL --client-id ID [--credential-ref REF]]');
+      return await connectMain(args, { cwd, out, env, fetchImpl, keyStore, ask });
     }
     if (command === 'check' && (args.source !== undefined || args.target !== undefined)) {
       if (typeof args.source !== 'string' || typeof args.target !== 'string') throw new ConfigError('check requires both --source URL and --target URL');
       const allowed = new Set(['_', 'source', 'target', 'scope', 'json', 'out']);
       if (Object.keys(args).some(key => key !== 'tag' && !allowed.has(key)) || args.tag.length || args._.length !== 1) throw new ConfigError('unsupported option for a single local check');
       if (args.out !== undefined && (typeof args.out !== 'string' || !args.out.trim())) throw new ConfigError('--out requires a file path');
-      const result = await checkToFile({ source: args.source, target: args.target, scope: args.scope }, args.out ? resolve(cwd, args.out) : null);
+      const result = await checkToFile({ source: args.source, target: args.target, scope: args.scope }, args.out ? resolve(cwd, args.out) : null,
+        { fetchImpl: localFetchImpl });
       out(args.json ? JSON.stringify(result, null, 2) : `${result.observation.state}  ${result.observation.reason}  ${result.checked_at}${args.out ? `  saved ${args.out}` : ''}`);
       return 0;
     }
@@ -306,7 +349,15 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
         if (!name || !path) throw new ConfigError(`--observations-of expects NAME=FILE, got "${value}"`);
         observationsOf[name] = path;
       }
-      const summary = await fleetSummary(pairs, { observationsOf });
+      const statesOf = {};
+      for (const value of [].concat(args['state-of'] ?? [])) {
+        const separator = String(value).indexOf('=');
+        const name = String(value).slice(0, separator), path = String(value).slice(separator + 1);
+        if (separator < 1 || !path || !pairs.some(project => project.name === name)) throw new ConfigError('--state-of expects a declared NAME=FILE');
+        if (Object.hasOwn(statesOf, name)) throw new ConfigError(`Duplicate state input for ${name}`);
+        statesOf[name] = path;
+      }
+      const summary = await fleetSummary(pairs, { observationsOf, statesOf });
       if (args.json) { out(JSON.stringify(summary, null, 1)); return 0; }
       return renderFleet(summary, out);
     }
@@ -320,7 +371,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       // DP-0017's context surface owns its config and files and needs no ledger, so it runs
       // before the ledger check below. contextMain parses its own argv; hand it everything
       // after the command word (found positionally, because flags may precede it).
-      return await contextMain(argv.slice(argv.indexOf(command) + 1), { cwd, out, err });
+      return await contextMain(argv.slice(argv.indexOf(command) + 1), { cwd, out, err,signal });
     }
     if (command === 'doctor') {
       // Doctor must run exactly where the ledger cannot be trusted yet: its job is to name
@@ -328,7 +379,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       // file itself. Takes no flags and repairs nothing. Awaited on purpose: a promise returned
       // from inside the try escapes the ConfigError handler below, and a disagreeing pair of
       // token spellings would surface as a stack trace instead of the exit-2 message.
-      return await doctorMain(argv.slice(argv.indexOf(command) + 1), { cwd, out, err });
+      return await doctorMain(argv.slice(argv.indexOf(command) + 1), { cwd, out, err, env });
     }
 
     const config = await loadConfig({ cwd });
@@ -392,6 +443,7 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       // so it is unchanged by a cosmetic edit to the template and changes the moment a figure does.
       const asOf = args['as-of'] === true ? null : (args['as-of'] ?? null);
       const dataset = freezeDataset(ledger.entries, observations.rows, {
+        activityState: await readState(config.paths.state),
         asOf: asOf ?? new Date().toISOString().slice(0, 10),
         title: args.title === true ? 'Backlink report' : (args.title ?? 'Backlink report'),
         includeNotes: args['include-notes'] === true,
@@ -500,24 +552,29 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
     }
 
     if (command === 'status' || command === 'diff') {
-      const found = command === 'status' ? disagreements(ledger.entries, observations.rows) : transitions(observations.rows);
-      if (args.json) { out(JSON.stringify(found, null, 1)); return 0; }
+      const activityState = command === 'status' ? await readState(config.paths.state) : null;
+      const found = command === 'status' ? disagreements(ledger.entries, observations.rows, { state: activityState }) : transitions(observations.rows);
+      const activity = command === 'status' && args.all ? projectPlacements(ledger.entries, observations.rows, { state: activityState }).map(({ entry, row, ...facts }) => ({ id: entry.id, source: entry.source, target: entry.target, scope: entry.scope, ...facts })) : null;
+      if (args.json) { out(JSON.stringify(activity ? { disagreements: found, placements: activity } : found, null, 1)); return 0; }
       reportProblems(ledger.problems, 'ledger line(s)', out);
       if (command === 'diff') {
         if (!found.length) out('no state changes recorded');
         for (const change of found.slice(0, 100)) out(`  ${change.at.slice(0, 10)}  ${change.from} -> ${change.to}  ${change.id}`);
         return 0;
       }
-      const groups = { appeared: 'appeared', lost: 'LOST', suspected_missing: 'suspected missing', cannot_say: 'cannot say', never_checked: 'never checked' };
+      const groups = { appeared: 'appeared', lost: 'confirmed missing', suspected_missing: 'suspected missing', cannot_say: 'cannot say', never_checked: 'never checked' };
       for (const [kind, label] of Object.entries(groups)) {
         const rows = found.filter(item => item.kind === kind);
         if (!rows.length) continue;
         out(`\n${label} (${rows.length})`);
         for (const item of rows.slice(0, 50)) {
           out(`  ${item.entry.id}  ${item.entry.source}${item.row ? `  [${item.row.reason}]` : ''}`);
+          out(`    Latest attempt: ${item.activity?.latest_attempt?.checked_at ?? 'not retained'} (${item.activity?.latest_attempt?.reason ?? 'unknown'})`);
+          out(`    Last conclusive: ${item.activity?.last_successful_observation?.checked_at ?? 'not retained'}; last link verification: ${item.activity?.last_link_verification?.checked_at ?? 'not retained'}`);
         }
       }
       if (!found.length) out('intent and observations agree on every entry');
+      if (activity) for (const item of activity) out(`  ${item.id}: latest attempt ${item.latest_attempt?.checked_at ?? 'not retained'}; last conclusive ${item.last_successful_observation?.checked_at ?? 'not retained'}; last link verification ${item.last_link_verification?.checked_at ?? 'not retained'}`);
       return 0;
     }
 
@@ -590,13 +647,14 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       if (ledger.problems.length) { reportProblems(ledger.problems, 'ledger line(s)', err); return 2; }
       const state = await readState(config.paths.state);
       const selected = selectEntries(ledger.entries, { filter: args.filter === true ? null : args.filter });
-      const entries = args.all ? selected : dueEntries(selected, lastCheckedMap(state));
+      const entries = args.all ? selected : dueEntries(selected, lastCheckedMap(state, selected));
       if (!entries.length) { (args.json ? err : out)(`nothing due (${plural(selected.length, 'entry', 'entries')} in scope; pass --all to recheck)`); return 0; }
       if (!args.json) err(`checking ${plural(entries.length, 'entry', 'entries')}…`);
       const rows = await runCheck(entries, {
         concurrency: Number(args.concurrency ?? config.defaults.concurrency ?? DEFAULTS.concurrency),
         timeoutMs: Number(args.timeout ?? config.defaults.timeoutMs ?? DEFAULTS.timeoutMs),
         hostDelayMs: Number(args['host-delay'] ?? config.defaults.hostDelayMs ?? DEFAULTS.hostDelayMs),
+        fetchImpl: localFetchImpl,
       });
       // The mirror records changes; `state.json` records activity. Appending a row that says
       // the same thing as the one above it is 2 KB of git churn per link per run, and the only
@@ -625,6 +683,13 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd(),
       err(JSON.stringify({error: {code: error.code, status: error.status, next: 'Keep this project ledger and its history. Resolve authorized read access for the configured project, then retry agentlinkops sync --pull-only --recover-cursors. Do not broaden grants or replay remote writes.'}}));
       return 2;
     }
+    if (command === 'sync' && error instanceof CloudError && error.status === 0 &&
+        ['CLOUD_TIMEOUT', 'CLOUD_NETWORK_ERROR'].includes(error.code)) {
+      // A local transport failure cannot establish whether a write committed.
+      // Print trusted recovery guidance, never attached exception/server text.
+      err(`agentlinkops: ${error.code}\nThe request outcome is unknown. Check the operation result before sending it again. Keep this project ledger and its history. Inspect accessible watches and their local references with agentlinkops sync --pull-only --recover-cursors. Do not broaden grants or replay remote writes.`);
+      return 2;
+    }
     err(`agentlinkops: ${error?.message ?? error}`);
     return 2;
   } finally {

package/cli/mcp-client.js

@@ -62,7 +62,7 @@ function retryDelay(error, attempt, now) {
 
 async function sdkClient({url, token, workspaceId, fetchImpl}) {
   const {Client, StreamableHTTPClientTransport} = await import('@modelcontextprotocol/client');
-  const client = new Client({name: 'agentlinkops-cli', version: '0.6.11'});
+  const client = new Client({name: 'agentlinkops-cli', version: '0.6.16'});
   const destination = new URL(url);
   const transport = new StreamableHTTPClientTransport(destination, {
     authProvider: {token: async () => token},
@@ -71,7 +71,7 @@ async function sdkClient({url, token, workspaceId, fetchImpl}) {
       if (target.href !== destination.href) fail('OAUTH_TOKEN_DESTINATION_MISMATCH');
       const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
       if (workspaceId) headers.set('X-Workspace-ID', workspaceId);
-      headers.set('User-Agent', 'agentlinkops-cli/0.6.11');
+      headers.set('User-Agent', 'agentlinkops-cli/0.6.16');
       const response = await fetchImpl(input, {...init, headers, redirect: 'error', signal: AbortSignal.timeout(30000)});
       if (response.redirected || response.status >= 300 && response.status < 400
         || response.url && response.url !== destination.href) fail('OAUTH_TOKEN_DESTINATION_MISMATCH');