agentlinkops 0.6.1 → 0.6.3

package/src/citations/stats.js

@@ -1,16 +1,15 @@
-// The statistics: closed-form and boring on purpose.
+// Fixed-epoch summaries plus explicitly qualified sequential inference.
 //
-// Wilson intervals over fixed-n epochs. No bootstrap, no resampling, no early
-// stopping — the IQRush finding that bootstrap CIs can be non-monotone in n is why
-// the epoch size is committed before the epoch starts. Anything cleverer (confidence
-// sequences, SPRT, changepoint dating) is a v2 design decision with its own gate,
-// recorded in DP-0031's contract, and does not ship until it is validated against
-// published data.
+// Wilson intervals describe each precommitted fixed-n epoch. Supplemental
+// confidence sequences and likelihood ratios have their own assumptions and
+// multiplicity budgets; they do not authorize optional sample collection.
+// Bayesian run-length outputs are exploratory model posteriors, not calibrated
+// alarm probabilities or verified dates of a real-world change.
 export const WILSON_Z = 1.959963985; // two-sided 95%
 
 /** Wilson score interval for k successes in n rendered runs. null when n is 0. */
 export function wilsonInterval(k, n, z = WILSON_Z) {
-  if (!Number.isFinite(k) || !Number.isFinite(n) || n <= 0 || k < 0 || k > n) return null;
+  if (!validCounts(k, n) || n === 0 || !Number.isFinite(z) || z <= 0) return null;
   const p = k / n;
   const z2 = z * z;
   const denom = 1 + z2 / n;
@@ -21,7 +20,7 @@ export function wilsonInterval(k, n, z = WILSON_Z) {
 
 /** Laplace-smoothed rate. (k+1)/(n+2) never reports 0 or 1 from finite data. */
 export function smoothedRate(k, n) {
-  if (n <= 0) return null;
+  if (!validCounts(k, n) || n === 0) return null;
   return (k + 1) / (n + 2);
 }
 
@@ -55,7 +54,8 @@ export function classifyEpoch(current, baseline, limits) {
 export function tallyOutcomes(outcomes) {
   let k = 0, n = 0, unknowns = 0, mentioned = 0;
   for (const outcome of outcomes) {
-    if (outcome === 'unknown') { unknowns += 1; continue; }
+    if (outcome === 'unknown' || outcome === null) { unknowns += 1; continue; }
+    if (!['cited','verified','mentioned','not_cited'].includes(outcome)) throw new RangeError('Unknown citation outcome');
     n += 1;
     if (outcome === 'cited' || outcome === 'verified') k += 1;
     if (outcome === 'mentioned') mentioned += 1;
@@ -68,70 +68,142 @@ export function tallyOutcomes(outcomes) {
  * "lost"; it states both rates with their intervals and sample sizes.
  */
 export function describeChange(current, baseline) {
+  if (current.rate === null || current.ci_low === null || current.ci_high === null) return 'insufficient data: citation rate unknown (no interpretable observations)';
   const fmt = (e) => `${e.rate.toFixed(2)} (${e.ci_low.toFixed(2)}–${e.ci_high.toFixed(2)}, n=${e.n})`;
   if (!baseline) return `first epoch: citation rate ${fmt(current)}`;
   return `citation rate moved from ${fmt(baseline)} to ${fmt(current)} between epochs`;
 }
 
-// === v2 statistics (DP-0045): the borrow-list math that makes alerts trustworthy ===
+// Sequential contracts and derivations are recorded in DP-0045/statistics-spec.md.
+function validCounts(k, n) { return Number.isSafeInteger(k) && Number.isSafeInteger(n) && n >= 0 && k >= 0 && k <= n; }
+function probability(value, name) { if (!Number.isFinite(value) || value <= 0 || value >= 1) throw new RangeError(`${name} must lie strictly between zero and one`); }
+function multiplicity(alpha, comparisons) {
+  probability(alpha, 'alpha');
+  if (!Number.isSafeInteger(comparisons) || comparisons < 1) throw new RangeError('comparisons must be a positive preregistered count');
+  return alpha / comparisons;
+}
+function binary(value) {
+  if (value === null || value === 'unknown') return null;
+  if (value === 1 || value === 'cited' || value === 'verified') return 1;
+  if (value === 0 || value === 'not_cited' || value === 'mentioned') return 0;
+  throw new RangeError('Observations must be binary citation outcomes or explicit unknowns');
+}
+function boundedInterval(k, n, error) {
+  const radius = Math.sqrt(Math.log(2 / error) / (2 * n));
+  return [Math.max(0, k / n - radius), Math.min(1, k / n + radius)];
+}
+
+/** Anytime interval via Hoeffding plus alpha/[m*n*(n+1)] spending.
+ * Independent Bernoulli observations with a constant mean are sufficient.
+ * Unknown exclusion additionally assumes missingness does not select outcomes.
+ * Union bounds cover every observed n and all m preregistered comparisons.
+ * This conservative construction is not the variance-adaptive confseq algorithm.
+ */
+export function confidenceSequence(observations, { alpha = 0.05, comparisons = 1 } = {}) {
+  const perCell = multiplicity(alpha, comparisons);
+  let k = 0, n = 0, unknowns = 0, lower = 0, upper = 1;
+  return observations.map(value => {
+    const x = binary(value);
+    if (x === null) unknowns += 1;
+    else {
+      n += 1; k += x;
+      const current = boundedInterval(k, n, perCell / (n * (n + 1)));
+      lower = Math.max(lower, current[0]); upper = Math.min(upper, current[1]);
+    }
+    return { k, n, unknowns, interval: n === 0 || lower > upper ? null : [lower, upper],
+      status: n === 0 ? 'insufficient_data' : lower > upper ? 'model_conflict' : 'available',
+      method: 'hoeffding-alpha-spending', alpha, comparisons };
+  });
+}
+
+/** Conservative fixed-n two-epoch difference interval. Both means receive half
+ * the per-comparison alpha. Repeated testing of many epoch pairs requires the
+ * total comparison count to be allocated in advance; no perpetual-alert claim.
+ */
+export function compareEpochs(current, baseline, { alpha = 0.05, comparisons = 1 } = {}) {
+  const error = multiplicity(alpha, comparisons) / 2;
+  if (!current || !baseline || !validCounts(current.k,current.n) || !validCounts(baseline.k,baseline.n) || current.n === 0 || baseline.n === 0)
+    return { verdict: 'insufficient_data', interval: null, alpha, comparisons, method: 'fixed-n-hoeffding-difference' };
+  const now = boundedInterval(current.k,current.n,error), prior = boundedInterval(baseline.k,baseline.n,error);
+  const interval = [Math.max(-1,now[0]-prior[1]),Math.min(1,now[1]-prior[0])];
+  return { verdict: interval[1] < 0 ? 'declined' : interval[0] > 0 ? 'grown' : 'not_distinguishable', interval, alpha, comparisons, method: 'fixed-n-hoeffding-difference' };
+}
 
-/** Wald sequential probability ratio test for a decline from baseline rate.
- * Returns { decision: 'decline' | 'accept' | 'continue', evidence: number }.
- * The SPRT fires the moment the evidence crosses either threshold — no fixed
- * n needed, which is exactly what monitoring at unknown-noise surfaces wants.
- * Thresholds follow the standard H0: p = p0 (baseline) vs H1: p = p1 (decline). */
+/** Simple-hypothesis sequential likelihood ratio with conservative Ville
+ * boundaries. p0/p1 must be selected before inspecting these observations;
+ * inserting an estimated prior-epoch rate does not retain the stated guarantees.
+ * A lower boundary supports p0 against p1; it does not establish stability.
+ */
 export function sprtDecline(k, n, baselineRate, declineRate = baselineRate * 0.5, alpha = 0.05, beta = 0.10) {
-  if (n === 0 || k > n) return { decision: 'continue', evidence: 0 };
-  const p0 = Math.max(baselineRate, 0.001);
-  const p1 = Math.max(declineRate, 0.001);
-  // Log-likelihood ratio
-  const llr = k * Math.log(p1 / p0) + (n - k) * Math.log((1 - p1) / (1 - p0));
-  const upper = Math.log((1 - beta) / alpha);
-  const lower = Math.log(beta / (1 - alpha));
-  // Positive LLR favors H1 (the rate has declined); negative favors H0 (still at baseline).
-  if (llr >= upper) return { decision: 'decline', evidence: Number(llr.toFixed(4)) };
-  if (llr <= lower) return { decision: 'stable', evidence: Number(llr.toFixed(4)) };
-  return { decision: 'continue', evidence: Number(llr.toFixed(4)) };
+  if (!validCounts(k,n)) throw new RangeError('SPRT requires valid integer counts');
+  probability(baselineRate,'baselineRate'); probability(declineRate,'declineRate'); probability(alpha,'alpha'); probability(beta,'beta');
+  if (declineRate >= baselineRate) throw new RangeError('declineRate must be below the prespecified baselineRate');
+  const evidence = k * Math.log(declineRate / baselineRate) + (n-k) * Math.log((1-declineRate)/(1-baselineRate));
+  return { decision: evidence >= Math.log(1/alpha) ? 'decline' : evidence <= Math.log(beta) ? 'baseline_supported' : 'continue', evidence,
+    upper: Math.log(1/alpha), lower: Math.log(beta), method: 'simple-hypothesis-likelihood-ratio' };
 }
 
-/** Bayesian online changepoint detection (simplified run-length posterior).
- * Takes a binary sequence (1 = cited, 0 = not cited) and returns the most
- * likely changepoint index, or null if no changepoint is detected.
- * This is the "when did it shift" answer that epoch-over-epoch comparison
- * can never give. */
-export function detectChangepoint(observations, { hazard = 0.1, threshold = 0.3 } = {}) {
-  if (observations.length < 6) return null;
-  const n = observations.length;
-  // Simple two-segment maximum likelihood: for each split point, compute
-  // the log-likelihood of segment 1 and segment 2 under Bernoulli models.
-  // The best split is the changepoint candidate.
-  let bestSplit = null;
-  let bestScore = -Infinity;
-  for (let split = 3; split <= n - 3; split += 1) {
-    const seg1 = observations.slice(0, split);
-    const seg2 = observations.slice(split);
-    const p1 = (seg1.reduce((a, b) => a + b, 0) + 1) / (seg1.length + 2);
-    const p2 = (seg2.reduce((a, b) => a + b, 0) + 1) / (seg2.length + 2);
-    // Skip trivially-identical segments
-    if (Math.abs(p1 - p2) < threshold) continue;
-    const ll1 = seg1.reduce((acc, x) => acc + Math.log(x ? p1 : 1 - p1), 0);
-    const ll2 = seg2.reduce((acc, x) => acc + Math.log(x ? p2 : 1 - p2), 0);
-    // Penalize the split by the hazard rate
-    const score = ll1 + ll2 + Math.log(1 - hazard) * (n - split - 1) + Math.log(hazard);
-    if (score > bestScore) { bestScore = score; bestSplit = split; }
+/** Exact Beta-Bernoulli BOCD filtering with constant hazard. The posterior is
+ * conditional on this piecewise-iid model and the chosen prior/hazard. It is not
+ * a confidence sequence, an FDR-controlled detector or ground-truth dating.
+ * Indices refer to the supplied observation array, preserving unknown gaps.
+ */
+export function changepointPosterior(observations, { hazard = 0.01, priorAlpha = 1, priorBeta = 1, minSegment = 3, posteriorThreshold = 0.8, minEffect = 0.3 } = {}) {
+  probability(hazard,'hazard'); probability(posteriorThreshold,'posteriorThreshold');
+  if (![priorAlpha,priorBeta].every(x=>Number.isFinite(x)&&x>0) || !Number.isInteger(minSegment) || minSegment<2 || !Number.isFinite(minEffect) || minEffect<0 || minEffect>1)
+    throw new RangeError('Invalid changepoint prior or selection parameters');
+  const known = [];
+  observations.forEach((value,index) => { const x=binary(value); if(x!==null)known.push({x,index}); });
+  if(known.length>2000)throw new RangeError('Exact BOCD is bounded to 2000 known observations; select a disclosed analysis window');
+  let posterior=[1], successes=[0], counts=[0];
+  for(const {x} of known){
+    const next=new Array(posterior.length+1).fill(0);
+    for(let r=0;r<posterior.length;r++){
+      const predictive=(x?priorAlpha+successes[r]:priorBeta+counts[r]-successes[r])/(priorAlpha+priorBeta+counts[r]);
+      const joint=posterior[r]*predictive;
+      next[0]+=joint*hazard;next[r+1]=joint*(1-hazard);
+    }
+    const sum=next.reduce((a,b)=>a+b,0);posterior=next.map(value=>value/sum);
+    successes=[0,...successes.map(value=>value+x)];counts=[0,...counts.map(value=>value+1)];
   }
-  return bestSplit;
+  const n=known.length, candidates=[];
+  for(let r=minSegment;r<=n-minSegment;r++)candidates.push({split:n-r,index:known[n-r].index,probability:posterior[r]});
+  const changeProbability=candidates.reduce((sum,row)=>sum+row.probability,0);
+  const best=candidates.reduce((best,row)=>!best||row.probability>best.probability?row:best,null);
+  let candidate=null;
+  if(best && changeProbability>=posteriorThreshold){
+    const before=known.slice(0,best.split),after=known.slice(best.split);
+    const delta=smoothedRate(after.reduce((sum,row)=>sum+row.x,0),after.length)-smoothedRate(before.reduce((sum,row)=>sum+row.x,0),before.length);
+    if(Math.abs(delta)>=minEffect && best.probability > posterior[n])candidate={index:best.index,known_split:best.split,delta};
+  }
+  // A conditional posterior location interval, never a frequentist date CI.
+  let locationInterval=null;
+  if(candidate && changeProbability>0){
+    let sum=0,low=null,high=null;
+    for(const row of candidates.slice().sort((a,b)=>a.index-b.index)){
+      sum+=row.probability/changeProbability;
+      if(low===null && sum>=0.025)low=row.index;
+      if(high===null && sum>=0.975)high=row.index;
+    }
+    locationInterval=[low,high??candidates[0].index];
+  }
+  return { method:'beta-bernoulli-bocd', interpretation:'exploratory', n, unknowns:observations.length-n, hazard,
+    run_length_posterior:posterior, candidate, location_interval:locationInterval, interior_change_probability:changeProbability,
+    no_change_probability:posterior[n]??1 };
 }
 
-/** Laplace-smoothed rate for a rolling window of observations. Used for the
- * trend sparkline in reports — shows the recent direction without claiming
- * statistical significance. */
+/** Compatibility helper: an exploratory boundary index, never an exact date. */
+export function detectChangepoint(observations, options = {}) { return changepointPosterior(observations,options).candidate?.index ?? null; }
+
+/** Descriptive Laplace rates over original-position windows. Unknowns occupy
+ * time positions but contribute neither success nor denominator. */
 export function rollingRate(observations, windowSize = 5) {
-  const rates = [];
-  for (let i = 0; i < observations.length; i += 1) {
-    const start = Math.max(0, i - windowSize + 1);
-    const window = observations.slice(start, i + 1);
-    rates.push(smoothedRate(window.reduce((a, b) => a + b, 0), window.length));
+  if(!Number.isSafeInteger(windowSize)||windowSize<1)throw new RangeError('windowSize must be a positive integer');
+  const values=observations.map(binary),rates=[];let k=0,n=0;
+  for(let i=0;i<values.length;i++){
+    if(values[i]!==null){n++;k+=values[i];}
+    if(i>=windowSize && values[i-windowSize]!==null){n--;k-=values[i-windowSize];}
+    rates.push(smoothedRate(k,n));
   }
   return rates;
 }

package/src/citations/sync.js

@@ -0,0 +1,131 @@
+// `agentlinkops citation sync` — push local epoch rows to the hosted API
+// so the console Citations view shows real data without the hosted scheduler.
+// Reads the local citations-epochs.jsonl and POSTs each row to the hosted
+// citation_epochs endpoint via the existing REST client.
+//
+// The sync is one-way (local → hosted) and idempotent: the hosted side
+// deduplicates by epoch_id + cell_id. The local ledger is the source of
+// truth; the hosted view is a projection.
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+export async function syncEpochs({ dir, api, workspaceId, projectId }) {
+  if (!api || !workspaceId || !projectId) {
+    throw new Error('citation sync needs api, workspaceId and projectId (connect first: agentlinkops connect)');
+  }
+
+  const epochsPath = join(resolve(dir), 'citations-epochs.jsonl');
+  let text;
+  try {
+    text = await readFile(epochsPath, 'utf8');
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return { synced: 0, total: 0, errors: 0, note: 'no local epochs found' };
+  }
+
+  const rows = text.split('\n').filter((l) => l.trim()).map((l) => {
+    return JSON.parse(l);
+  });
+
+  if (rows.length === 0) return { synced: 0, total: 0, errors: 0, note: 'epoch file is empty' };
+
+  const normalizedRates = rows.filter(row => Number.isInteger(row.n) && Number.isInteger(row.k) && row.n >= 0 && row.k >= 0 && row.k <= row.n && row.rate !== (row.n ? row.k / row.n : null)).length;
+  // Legacy smoothed rates are projected from retained counts; never rewrite the local ledger.
+  // Send the epoch rows in batches (the API accepts up to 100 per call)
+  let synced = 0;
+  let errors = 0;
+  for (let i = 0; i < rows.length; i += 100) {
+    const batch = rows.slice(i, i + 100).map((row) => ({
+      workspace_id: workspaceId,
+      project_id: projectId,
+      epoch_id: row.epoch_id,
+      cell_id: row.cell_id,
+      k: row.k,
+      n: row.n,
+      unknowns: row.unknowns ?? 0,
+      mentioned: row.mentioned ?? 0,
+      rate: row.n === 0 ? null : row.k / row.n,
+      ci_low: row.n === 0 ? null : row.ci_low,
+      ci_high: row.n === 0 ? null : row.ci_high,
+      classification: row.classification,
+      baseline_epoch_id: row.baseline?.epoch_id ?? null,
+      baseline_rate: row.baseline?.rate ?? null,
+      baseline_ci_low: row.baseline?.ci_low ?? null,
+      baseline_ci_high: row.baseline?.ci_high ?? null,
+      spent_estimate_usd: row.spent_estimate_usd ?? 0,
+      at: row.at,
+    }));
+
+    try {
+      await api('/v1/commands/sync_citation_epochs', {
+        method: 'POST',
+        body: { epochs: batch, projectId },
+      });
+      synced += batch.length;
+    } catch (cause) {
+      errors += batch.length;
+      console.error(`sync batch failed: ${cause.message}`);
+    }
+  }
+
+  return { synced, errors, total: rows.length, ...(normalizedRates ? { normalized_rates: normalizedRates, normalization: 'Hosted rates projected as k/n (null for n=0); local ledger unchanged.' } : {}) };
+}
+
+// Explicit opt-in: raw retained answer text leaves the local ledger only here.
+export async function syncEvidence({ dir, api, projectId, cliVersion }) {
+  const { lstat, realpath } = await import('node:fs/promises');
+  const { createHash } = await import('node:crypto');
+  const { evidenceEnvelopeSchema } = await import('./contract.js');
+  const { CITATION_EVIDENCE_LIMITS: limits, citationEvidenceRecordInput } = await import('../../shared/citation-evidence-contract.js');
+  if (!api || !projectId || !cliVersion) throw new Error('Evidence sync requires a connected project and CLI version');
+  const root = await realpath(resolve(dir));
+  let text;
+  try { text = await readFile(join(root, 'citations-observations.jsonl'), 'utf8'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; return { synced: 0, total: 0, skipped: 0, errors: 0, reasons: {} }; }
+  const rows = text.split('\n').filter(line => line.trim()).map(line => JSON.parse(line));
+  const records = []; const reasons = {}; const seen = new Set();
+  const skip = reason => { reasons[reason] = (reasons[reason] ?? 0) + 1; };
+  const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+  async function safeFile(path) {
+    const actual = await realpath(path);
+    if (!actual.startsWith(root + '/') || !(await lstat(path)).isFile()) throw new Error('Evidence path is not a regular ledger file');
+    return actual;
+  }
+  // Validate the complete local selection before sending any evidence batch.
+  for (const row of rows) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(row.epoch_id ?? '') || ['.', '..'].includes(row.epoch_id) || !/^[a-f0-9]{64}$/.test(row.evidence_sha256 ?? '')) throw new Error('Malformed local evidence reference');
+    const path = join(root, 'citations/evidence', row.epoch_id, `${row.evidence_sha256}.json`);
+    if (seen.has(path)) continue; seen.add(path);
+    let file;
+    try { file = await safeFile(path); } catch (error) { if (error.code === 'ENOENT') { skip('missing_envelope'); continue; } throw error; }
+    if ((await lstat(file)).size > limits.envelopeBytes) throw new Error('Evidence envelope exceeds the upload limit');
+    const envelopeJson = await readFile(file, 'utf8');
+    const envelope = evidenceEnvelopeSchema.parse(JSON.parse(envelopeJson));
+    if (envelope.epoch_id !== row.epoch_id || envelope.cell_id !== row.cell_id || envelope.run_index !== row.run_index) throw new Error('Evidence identity does not match its observation');
+    if (envelope.engine_identity.startsWith('google-aio:') && !envelope.provenance) { skip('legacy_aio_without_provenance'); continue; }
+    const record = { envelopeJson, sha256: hash(envelopeJson), cliVersion, localEvidenceSha256: row.evidence_sha256 };
+    if (envelope.screenshot_file) {
+      if (!/^[A-Za-z0-9_.-]+$/.test(envelope.screenshot_file) || ['.', '..'].includes(envelope.screenshot_file)) throw new Error('Unsafe screenshot reference');
+      record.screenshot = { reference: envelope.screenshot_file, sha256: null };
+      try {
+        const image = await safeFile(join(root, 'citations/evidence', row.epoch_id, envelope.screenshot_file));
+        if ((await lstat(image)).size <= 10 * 1024 * 1024) record.screenshot.sha256 = hash(await readFile(image));
+      } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    records.push(citationEvidenceRecordInput.parse(record));
+  }
+  const batches = []; let batch = [];
+  const bytes = records => Buffer.byteLength(JSON.stringify({ projectId, records }));
+  for (const record of records) {
+    if (bytes([record]) > limits.requestBytes) throw new Error('Encoded evidence exceeds the request limit');
+    if (batch.length && (batch.length >= limits.records || bytes([...batch, record]) > limits.requestBytes)) { batches.push(batch); batch = []; }
+    batch.push(record);
+  }
+  if (batch.length) batches.push(batch);
+  let synced = 0; let errors = 0;
+  for (const records of batches) {
+    try { await api('/v1/commands/ingest_citation_evidence', { method: 'POST', body: { projectId, records } }); synced += records.length; }
+    catch { errors += records.length; }
+  }
+  return { synced, total: seen.size, skipped: Object.values(reasons).reduce((a, b) => a + b, 0), errors, reasons };
+}

package/src/citations/watch.js

@@ -1,85 +1,65 @@
-// The citation watch: register a cron entry that runs the epoch, generates
-// the report, and alerts on decline. This is what turns a measurement script
-// into a monitoring product — the buyer sets it up once and gets weekly
-// evidence in their inbox.
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { join, resolve, basename } from 'node:path';
+// Local scheduling is explicit: no crontab is changed until register/remove is called.
+import { resolve, dirname, basename, join } from 'node:path';
 import { execFile } from 'node:child_process';
-import { homedir } from 'node:os';
+import { validateAlertWebhook } from './alert.js';
 
-const CADENCE_HOURS = { hourly: 1, daily: 24, weekly: 168, monthly: 720 };
+const CADENCES = { hourly: '17 * * * *', daily: '17 9 * * *', weekly: '17 9 * * 1', monthly: '17 9 1 * *' };
+const PREFIX = '# agentlinkops:citation-watch:';
+const quote = value => "'" + String(value).replace(/'/g, "'\\''") + "'";
 
-export async function registerWatch({ panelPath, cadence = 'weekly', dir, out }) {
-  if (!CADENCE_HOURS[cadence]) {
-    throw new Error(`unknown cadence: ${cadence} (known: ${Object.keys(CADENCE_HOURS).join(', ')})`);
-  }
-  const absolute = resolve(panelPath);
-  const panelName = basename(absolute, '.json');
-  const agentlinkopsBin = process.argv[1] ?? 'agentlinkops';
-  const ledgerDir = dir ?? join(homedir(), '.agentlinkops');
-  const reportDir = out ?? join(ledgerDir, 'citations', 'reports');
-
-  // The runner: epoch + report + alert in one shell line. The report path is
-  // deterministic so the alert hook can find the latest artifact.
-  const command = [
-    `cd ${join(absolute, '..')}`,
-    `&& ${agentlinkopsBin} citation run ${absolute}`,
-    `&& ${agentlinkopsBin} citation report ${absolute}`,
-    // The alert hook reads the latest epoch rows; if any cell declined,
-    // the report is flagged (delivery is a follow-up: email or webhook).
-    `&& ${agentlinkopsBin} citation alert ${absolute}`,
-  ].join(' ');
-
-  // Cron line: m h dom mon dow command — weekly on Monday at 09:17 UTC,
-  // daily at 09:17, hourly at minute 17 (off the :00 mark per convention).
-  const cronSpec = cadence === 'weekly' ? '17 9 * * 1'
-    : cadence === 'daily' ? '17 9 * * *'
-    : cadence === 'hourly' ? '17 * * * *'
-    : '17 9 1 * *'; // monthly
-
-  const marker = `# agentlinkops:citation-watch:${panelName}`;
-  const cronLine = `${cronSpec} ${command} 2>&1 | logger -t agentlinkops-citation ${marker}`;
-
-  // Read the existing crontab, replace our entry if present, append otherwise.
-  const existing = await new Promise((r) => {
-    execFile('crontab', ['-l'], (err, stdout) => r(err ? '' : stdout));
-  });
-  const lines = existing.split('\n').filter((l) => !l.includes(marker));
-  lines.push(cronLine);
-  await new Promise((r, j) => {
-    execFile('crontab', ['-'], { input: lines.join('\n') + '\n' }, (err) => err ? j(err) : r());
+function run(args, input, execFileImpl) {
+  return new Promise((resolveResult, reject) => {
+    const child = execFileImpl('crontab', args, (error, stdout, stderr) => {
+      if (!error) return resolveResult(stdout ?? '');
+      if (args[0] === '-l' && error.code === 1 && /^no crontab for [^\r\n]+\s*$/i.test((stderr ?? '').trim())) return resolveResult('');
+      reject(new Error('Unable to ' + (args[0] === '-l' ? 'read' : 'write') + ' crontab', { cause: error }));
+    });
+    if (input !== undefined) {
+      child.stdin.on('error', reject);
+      child.stdin.end(input);
+    }
   });
-
-  return {
-    cadence,
-    cronSpec,
-    panelPath: absolute,
-    marker,
-    next: cadence === 'weekly' ? 'next Monday 09:17 UTC' : `every ${CADENCE_HOURS[cadence]}h at :17`,
-  };
 }
-
-export async function listWatches() {
-  const existing = await new Promise((r) => {
-    execFile('crontab', ['-l'], (err, stdout) => r(err ? '' : stdout));
-  });
-  return existing.split('\n')
-    .filter((l) => l.includes('# agentlinkops:citation-watch:'))
-    .map((l) => {
-      const marker = l.match(/agentlinkops:citation-watch:(\S+)/);
-      const cronPart = l.split(/\s+/).slice(0, 5).join(' ');
-      return { panel: marker?.[1] ?? 'unknown', cron: cronPart };
-    });
+function markerName(value) {
+  if (!value || /[\r\n\0]/.test(value)) throw new Error('Invalid citation watch name');
+  return encodeURIComponent(value);
 }
-
-export async function removeWatch(panelName) {
-  const marker = `# agentlinkops:citation-watch:${panelName}`;
-  const existing = await new Promise((r) => {
-    execFile('crontab', ['-l'], (err, stdout) => r(err ? '' : stdout));
-  });
-  const lines = existing.split('\n').filter((l) => !l.includes(marker));
-  await new Promise((r, j) => {
-    execFile('crontab', ['-'], { input: lines.join('\n') + '\n' }, (err) => err ? j(err) : r());
-  });
+function replace(existing, marker, line) {
+  const lines = existing.split('\n').filter(value => value && !value.endsWith(marker));
+  if (line) lines.push(line);
+  return lines.join('\n') + (lines.length ? '\n' : '');
+}
+export async function registerWatch({ panelPath, cadence = 'weekly', dir, out, webhook, execFileImpl = execFile, binary = process.argv[1], nodeBinary = process.execPath }) {
+  if (!CADENCES[cadence]) throw new Error(`unknown cadence: ${cadence}`);
+  if (webhook) validateAlertWebhook(webhook);
+  const absolute = resolve(panelPath);
+  const ledgerDir = resolve(dir ?? join(dirname(absolute), '.agentlinkops'));
+  const reportPath = resolve(out ?? join(ledgerDir, 'citations', 'report.html'));
+  const marker = PREFIX + markerName(basename(absolute, '.json'));
+  for (const value of [absolute, ledgerDir, reportPath, binary, nodeBinary]) {
+    if (!value || /[\r\n\0]/.test(value)) throw new Error('Invalid citation watch path');
+  }
+  const cli = `${quote(nodeBinary)} ${quote(resolve(binary))}`;
+  const delivery = webhook ? ` --webhook ${quote(webhook)} --report ${quote(reportPath)}` : '';
+  const common = `${quote(absolute)} --dir ${quote(ledgerDir)}`;
+  // Exit 1 means an actionable decline, so it must still produce its report and alert.
+  const command = `cd ${quote(dirname(absolute))} && { ${cli} citation run ${common}; status=$?; if [ "$status" -le 1 ]; then ${cli} citation report ${common} --out ${quote(reportPath)} && ${cli} citation alert ${common}${delivery}; else exit "$status"; fi; }`;
+  // Cron interprets percent even inside shell quotes.
+  const cronLine = `${CADENCES[cadence]} ${command.replace(/%/g, '\\%')} 2>&1 | logger -t agentlinkops-citation ${marker}`;
+  const existing = await run(['-l'], undefined, execFileImpl);
+  await run(['-'], replace(existing, marker, cronLine), execFileImpl);
+  return { cadence, cronSpec: CADENCES[cadence], panelPath: absolute, marker, next: 'according to the crontab host timezone' };
+}
+export async function listWatches({ execFileImpl = execFile } = {}) {
+  const existing = await run(['-l'], undefined, execFileImpl);
+  return existing.split('\n').filter(line => line.includes(PREFIX)).map(line => ({
+    panel: decodeURIComponent(line.slice(line.lastIndexOf(PREFIX) + PREFIX.length)),
+    cron: line.trim().split(/\s+/).slice(0, 5).join(' '),
+  }));
+}
+export async function removeWatch(panelName, { execFileImpl = execFile } = {}) {
+  const marker = PREFIX + markerName(panelName);
+  const existing = await run(['-l'], undefined, execFileImpl);
+  await run(['-'], replace(existing, marker), execFileImpl);
   return { removed: panelName };
 }