phaedo-mcp 0.2.1 → 0.3.0

package/autonomy-promotion.js

@@ -0,0 +1,280 @@
+// §10.7 — fatigue-aware autonomy promotion.
+//
+// THE PROBLEM THIS SOLVES. Phaedo can add a gate and never remove one. The
+// delegation-promotion channel learns only from DISAGREEMENTS
+// (consult-core.js `buildDelegationPromotions`), and §10.5 permanently caps what
+// an authored disposition may do at `bias_cautious`: "an authored disposition may
+// make the agent MORE deferential, never less." Expanding autonomy requires the
+// subject to hand-author a `kind:"authorization"` rule with a `match`. Almost
+// nobody will. So in real use the oracle accumulates friction and never sheds it,
+// and the 2026 approval-fatigue literature is unanimous about where that ends:
+// approval stops being a decision and becomes a reflex, which is both a usability
+// failure and an attack surface.
+//
+// THE OBJECTION, AND WHY IT SHAPES THE DESIGN. "Learn from approvals" is exactly
+// what the honesty rail forbids — rubber stamps must not teach. That objection is
+// correct, and it is the reason this module is not a counter. A subject clicking
+// approve fourteen times in ninety seconds is not expressing a policy; they are
+// tired. So the gate here is not "how many approvals" but "is this evidence of
+// DELIBERATION":
+//
+//   - spread over distinct days, not a single sitting (volume ≠ deliberation)
+//   - no contrary evidence at all: one rejection or modification in the class kills it
+//   - the oracle must already be tracking the subject well in that domain
+//     (agreement rate — the interlock the agreement read-out exists to provide)
+//   - not batch-marked: approvals recorded in one burst are bookkeeping, not consent
+//
+// AND WHAT IS PROPOSED IS DELIBERATELY SMALL. Reversible only. Never `high`
+// magnitude. A priced class is bounded by an `amount_lt` CEILING set to the
+// SECOND-highest amount approved, never the highest — one outlier must not set the
+// bar (see spendCeiling). Always `require_binding: true`, so the relaxation cannot
+// be unlocked by a fabricated descriptor. Always `expires_at`, so an autonomy grant
+// the subject stops wanting lapses by itself.
+//
+// AND IT IS STILL ONLY A PROPOSAL. This writes nothing authored. It stages a
+// `suggested_rules` entry the subject reviews and endorses, exactly like every
+// other promotion channel — the authored-only invariant holds. The producer
+// stages; the user authors.
+//
+// PURE: (receipts, fp, agreement, opts) -> suggestions[]. No I/O, no globals.
+
+import { computeAgreement, DEFAULT_WINDOW_DAYS } from './agreement.js';
+
+// ── The bar. Every one of these is a way of asking "was this deliberate?" ─────
+export const MIN_APPROVALS = 5;          // enough instances to be a pattern
+export const MIN_DISTINCT_DAYS = 3;      // ...spread across days, not one sitting
+export const MIN_AGREEMENT = 0.8;        // ...in a domain the oracle already tracks well
+export const MIN_AGREEMENT_SCORED = 5;   // ...on enough scored decisions to mean anything
+export const BATCH_WINDOW_MS = 60_000;   // marks this close together are bookkeeping
+export const MAX_BATCH_FRACTION = 0.5;   // ...and may not carry the majority of the evidence
+export const DEFAULT_TTL_DAYS = 30;      // a grant expires unless re-earned
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const MAG_RANK = { low: 0, medium: 1, high: 2 };
+const RANK_MAG = ['low', 'medium', 'high'];
+
+const uuid = () =>
+  (typeof crypto !== 'undefined' && crypto.randomUUID) ? crypto.randomUUID()
+    : `aut-${Math.random().toString(36).slice(2, 10)}`;
+
+const utcDay = (iso) => String(iso || '').slice(0, 10);   // RFC 3339 → YYYY-MM-DD
+
+// A promotable class is (domain × reversible-true). Magnitude is not part of the
+// key — it is the CEILING we derive from what was actually observed, so a class
+// seen only at `low` never proposes a rule that would fire at `medium`.
+function classKey(domain) { return String(domain || '').toLowerCase(); }
+
+// Receipts that count as evidence FOR autonomy in a class. Deliberately narrow:
+// the oracle must have been decisive, the subject must have approved, and the
+// action must be one we would ever propose relaxing.
+function isPromotableApproval(r) {
+  const ad = r?.request?.action_descriptor || {};
+  if (r?.user_action !== 'approved') return false;
+  if (r?.response?.signal !== 'proceed' && r?.response?.signal !== 'proceed_with_note') return false;
+  if (ad.reversible !== true) return false;                       // irreversible is never auto-proceeded
+  if (ad.magnitude === 'high') return false;                      // nor is a major action
+  if (ad.amount !== undefined && !(typeof ad.amount === 'number' && Number.isFinite(ad.amount) && ad.amount >= 0))
+    return false;                                                 // a malformed amount is not evidence of anything
+  if (!ad.domain) return false;                                   // an unscoped autoproceed rule is a blank cheque
+  return true;
+}
+
+// The spend ceiling for a money class: the SECOND-highest amount approved, not the
+// highest.
+//
+// Using the maximum would let ONE outlier set the bar — approve five $20 orders and a
+// single $500 one, and the rule would thereafter auto-proceed anything up to $500.
+// Requiring two approvals at a level before the rule reaches it is the money-shaped
+// version of the "spread across days, not one sitting" rule: a bound has to be
+// demonstrated more than once.
+//
+// Returns null when the class carries no amounts at all (then no ceiling is needed),
+// or when fewer than two priced approvals exist (then no ceiling can be justified, so
+// the class is not promotable).
+export function spendCeiling(receipts) {
+  const amounts = receipts
+    .map((r) => r?.request?.action_descriptor?.amount)
+    .filter((a) => typeof a === 'number' && Number.isFinite(a));
+  if (!amounts.length) return null;                 // unpriced class — no ceiling needed
+  if (amounts.length < 2) return undefined;         // one priced approval cannot justify a bound
+  const sorted = amounts.slice().sort((a, b) => b - a);
+  return sorted[1];
+}
+
+// Anything that argues AGAINST relaxing this class. One is enough to disqualify:
+// a class the subject has ever rejected or edited is not settled.
+function isContraryEvidence(r, domain) {
+  const ad = r?.request?.action_descriptor || {};
+  if (classKey(ad.domain) !== domain) return false;
+  return r?.user_action === 'rejected' || r?.user_action === 'modified';
+}
+
+// Were these approvals RECORDED in a burst? Marking a screenful of receipts in one
+// pass is bookkeeping, not consent — so if most of the supporting evidence was
+// stamped inside one short window, it does not support a policy. Receipts without
+// a mark timestamp (older stores) are treated as non-batch: absence of evidence
+// is not evidence of fatigue, and the other gates still apply.
+export function batchFraction(receipts, { windowMs = BATCH_WINDOW_MS } = {}) {
+  const stamps = receipts
+    .map((r) => Date.parse(r?.user_action_at))
+    .filter((t) => Number.isFinite(t))
+    .sort((a, b) => a - b);
+  if (stamps.length < 2) return 0;
+  let best = 1;
+  for (let i = 0; i < stamps.length; i++) {
+    let j = i;
+    while (j < stamps.length && stamps[j] - stamps[i] <= windowMs) j++;
+    best = Math.max(best, j - i);
+  }
+  return best / receipts.length;
+}
+
+function proposedText(domain, magMax, ceiling = null) {
+  const scope = magMax === 'low' ? 'small, reversible' : 'routine, reversible';
+  // The ceiling is the single most consequential term on a money rule, so it belongs
+  // in the sentence the subject reads — not only in the terms line beneath it.
+  // "up to", not "under" — the ceiling is INCLUSIVE now (M7), and this sentence is what the
+  // subject reads before endorsing. Prose that says "under 20" for a rule that fires AT 20
+  // misdescribes the authority being granted, on the one screen where accuracy is consent.
+  const under = ceiling !== null ? ` up to ${ceiling}` : '';
+  return `Let agents go ahead with ${scope} ${domain} actions${under} without asking me first.`;
+}
+
+// (receipts, fp, opts) -> suggestion[]  — the §10.5 authorizations worth PROPOSING.
+//
+// `fp` supplies what is already authored or already staged, so an endorsed or
+// pending suggestion is never re-proposed (the no-nag rule every promotion
+// channel follows).
+export function buildAutonomyPromotions(receipts, fp, opts = {}) {
+  const {
+    now = Date.now(),
+    windowDays = DEFAULT_WINDOW_DAYS,
+    minApprovals = MIN_APPROVALS,
+    minDistinctDays = MIN_DISTINCT_DAYS,
+    minAgreement = MIN_AGREEMENT,
+    minAgreementScored = MIN_AGREEMENT_SCORED,
+    maxBatchFraction = MAX_BATCH_FRACTION,
+    ttlDays = DEFAULT_TTL_DAYS,
+  } = opts;
+
+  const list = Array.isArray(receipts) ? receipts : [];
+  const since = now - windowDays * DAY_MS;
+  const inWindow = list.filter((r) => {
+    const t = Date.parse(r?.created_at);
+    return Number.isFinite(t) && t >= since && t <= now;
+  });
+
+  // Already covered? An authored autoproceed for the domain, or a live suggestion.
+  const authored = new Set(
+    (Array.isArray(fp?.standing_rules) ? fp.standing_rules : [])
+      .filter((r) => r?.kind === 'authorization' && r?.effect === 'autoproceed')
+      .flatMap((r) => (Array.isArray(r?.match?.domains) ? r.match.domains : []).map(classKey)),
+  );
+  const staged = new Set(
+    (Array.isArray(fp?.suggested_rules) ? fp.suggested_rules : [])
+      .filter((s) => s?.source === 'autonomy_promotion')
+      .flatMap((s) => (Array.isArray(s?.match?.domains) ? s.match.domains : []).map(classKey)),
+  );
+
+  const agreement = computeAgreement(list, { windowDays, now });
+
+  const byClass = new Map();
+  for (const r of inWindow) {
+    if (!isPromotableApproval(r)) continue;
+    const key = classKey(r.request.action_descriptor.domain);
+    const bucket = byClass.get(key) || { receipts: [], days: new Set(), magRank: 0, clients: new Set() };
+    bucket.receipts.push(r);
+    bucket.days.add(utcDay(r.created_at));
+    bucket.magRank = Math.max(bucket.magRank, MAG_RANK[r.request.action_descriptor.magnitude] ?? 0);
+    // §10.5 scoping (step 5): WHICH paired client's actions earned this. Recorded from
+    // the receipt's `client_id` — the serving client, established out-of-band with the
+    // phone — never from `agent_id`, which is the caller's claim about itself.
+    if (typeof r.client_id === 'string' && r.client_id) bucket.clients.add(r.client_id);
+    byClass.set(key, bucket);
+  }
+
+  const out = [];
+  for (const [domain, bucket] of byClass) {
+    if (authored.has(domain) || staged.has(domain)) continue;          // no-nag
+    if (bucket.receipts.length < minApprovals) continue;               // not yet a pattern
+    if (bucket.days.size < minDistinctDays) continue;                  // one sitting is not a policy
+    if (inWindow.some((r) => isContraryEvidence(r, domain))) continue; // any pushback disqualifies the class
+    if (batchFraction(bucket.receipts, opts) > maxBatchFraction) continue;  // batch-marked = bookkeeping
+
+    // The interlock: don't hand autonomy to an oracle that isn't tracking this
+    // subject here. `(none)` is how computeAgreement keys undomained receipts.
+    const dom = agreement.domains[domain];
+    if (!dom || dom.scored < minAgreementScored || dom.rate === null || dom.rate < minAgreement) continue;
+
+    // Money needs a ceiling, and a ceiling needs to have been demonstrated twice.
+    // `undefined` means the class is priced but cannot justify a bound — skip it
+    // rather than propose an unbounded spend authorization.
+    const ceiling = spendCeiling(bucket.receipts);
+    if (ceiling === undefined) continue;
+    if (ceiling !== null && !(ceiling > 0)) continue;                  // a 0 ceiling can never match
+
+    const magMax = RANK_MAG[bucket.magRank] || 'low';
+
+    // §10.5 `agents` — scope the proposed grant to the clients that EARNED it.
+    //
+    // Only meaningful now that scoping is enforced (v0.1.53) and authorable on the
+    // phone (#197). Before that, writing this field would have shipped something that
+    // looked like a boundary and was not — the reason it was deliberately left off.
+    //
+    // Strictly narrowing versus the previous behaviour, which granted every paired
+    // client whatever any one of them earned. A client that contributed approvals but
+    // cannot be attributed (receipts written before v0.1.53 carry no `client_id`) is
+    // simply left out — it keeps asking, which is the fail-safe direction.
+    //
+    // The empty case is the one that matters: when NO receipt in the class can be
+    // attributed, the field is OMITTED rather than written as `[]`. Absent means
+    // unscoped (today's behaviour, preserved for pre-v0.1.53 history); `[]` means a
+    // scope naming nobody, which would stage a grant that can never fire. Getting
+    // those two confused is precisely the defect the v0.1.54 hardening pass caught.
+    const agents = [...bucket.clients].sort();
+    out.push({
+      suggestion_id: uuid(),
+      status: 'suggested',
+      kind: 'authorization',
+      source: 'autonomy_promotion',
+      proposed_text: proposedText(domain, magMax, ceiling),
+      match: {
+        domains: [domain],
+        reversible: true,
+        magnitude_max: magMax,
+        // INCLUSIVE (M7). This staged `amount_lt: ceiling`, and `ceiling` is the SECOND-HIGHEST
+        // amount approved — so five $20 approvals minted a rule matching `amount < 20`, which
+        // excludes every purchase that earned it. The grant was unfireable by construction, and
+        // silently: it appeared in the subject's rules, read correctly in prose, and never
+        // matched. §10.5 gained `amount_lte` for this.
+        ...(ceiling !== null ? { amount_lte: ceiling } : {}),
+      },
+      effect: 'autoproceed',
+      // Non-negotiable on a PROPOSED relaxation: it may only apply to a request
+      // bound to a concrete call, and it lapses unless the subject re-earns it.
+      require_binding: true,
+      expires_at: new Date(now + ttlDays * DAY_MS).toISOString(),
+      ...(agents.length ? { agents } : {}),
+      note: agents.length
+        // Say the grant is limited, without printing an opaque `c_…` the subject
+        // cannot recognise — only the phone holds the registry that names it.
+        ? `you have approved every ${domain} action like this that Phaedo has seen — limited to the agent that earned it`
+        : `you have approved every ${domain} action like this that Phaedo has seen`,
+      evidence: {
+        observation_count: bucket.receipts.length,
+        distinct_days: bucket.days.size,
+        agreement_rate: dom.rate,
+        evidence_basis: 'observed',
+        last_observed: bucket.receipts[bucket.receipts.length - 1]?.created_at || null,
+        // Provenance for the audit: how many paired clients this evidence came from,
+        // and whether any of it predates client attribution. Distinct from `agents`,
+        // which is the enforceable scope.
+        client_count: bucket.clients.size,
+        unattributed: bucket.receipts.some((r) => !(typeof r.client_id === 'string' && r.client_id)),
+      },
+      created: new Date(now).toISOString(),
+    });
+  }
+  // Deterministic order — this rides a last-write-wins mailbox deposit.
+  return out.sort((a, b) => a.match.domains[0].localeCompare(b.match.domains[0]));
+}

package/build-package.mjs

@@ -1,22 +1,37 @@
 #!/usr/bin/env node
-// Make the npm package self-contained. The MCP server reaches two sets of files at
-// the repo root (one source of truth, shared with the extension): the injection
-// renderer (context-block.js, via projection.js) and the classic crypto modules
-// (protocol/envelope/kdf/identity.js, via lib/phaedo-crypto.js). The published
-// package ships only mcp/, so this copies those root modules into mcp/vendor/;
-// projection.js and lib/phaedo-crypto.js prefer the vendored copies when present
-// and fall back to the repo root in dev. Runs as `prepack` (npm pack / publish)
-// and `npm run build`. Idempotent; mcp/vendor/ is gitignored (a build artifact).
+// Make the npm package self-contained. The MCP server reaches three sets of files
+// at the repo root (one source of truth, shared with the extension): the injection
+// renderer (context-block.js, via projection.js), the classic crypto modules
+// (protocol/envelope/kdf/identity.js, via lib/phaedo-crypto.js), and the capture
+// stack — capture/* for the SessionEnd hook plus the extraction modules the hook
+// and the mcp-local tier-3 fold need (loaded via lib/capture-home.js). The
+// published package ships only mcp/, so this copies those root modules into
+// mcp/vendor/ (capture/extraction keep their subdirectories — their imports are
+// intra-directory relative, so the copies resolve each other unchanged); the
+// consumers prefer the location per their own doc-comments. Runs as `prepack`
+// (npm pack / publish), `pretest`, and `npm run build`. Idempotent; mcp/vendor/
+// is gitignored (a build artifact).
 
 import { copyFileSync, mkdirSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import { ROOT_FILES, CAPTURE_FILES, EXTRACTION_FILES } from './vendored-files.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(HERE, '..');
 const VENDOR = join(HERE, 'vendor');
-const FILES = ['context-block.js', 'protocol.js', 'envelope.js', 'kdf.js', 'identity.js'];
+// Single source of truth, shared with scripts/export-public-repo.mjs (they drifted once).
+const FILES = ROOT_FILES;
+// The capture hook + tier-3 fold closure. Keep in lockstep with what
+// lib/capture-home.js consumers actually import — test-vendored-capture.mjs
+// exercises the whole set from a rootless copy, so a missing module fails CI.
+
+
 
 mkdirSync(VENDOR, { recursive: true });
 for (const f of FILES) copyFileSync(resolve(ROOT, f), join(VENDOR, f));
-process.stdout.write(`[phaedo-mcp] bundled ${FILES.length} root modules → mcp/vendor/\n`);
+mkdirSync(join(VENDOR, 'capture'), { recursive: true });
+for (const f of CAPTURE_FILES) copyFileSync(resolve(ROOT, 'capture', f), join(VENDOR, 'capture', f));
+mkdirSync(join(VENDOR, 'extraction'), { recursive: true });
+for (const f of EXTRACTION_FILES) copyFileSync(resolve(ROOT, 'extraction', f), join(VENDOR, 'extraction', f));
+process.stdout.write(`[phaedo-mcp] bundled ${FILES.length} root + ${CAPTURE_FILES.length} capture + ${EXTRACTION_FILES.length} extraction modules → mcp/vendor/\n`);

package/capture-a11y.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Phaedo — Track B a11y capture core (the Node side of the OS-accessibility helper).
+//
+// The native macOS helper (capture/spike-a11y-macos → the productized reader) observes a
+// chat app's accessibility tree, reconstructs the visible transcript into {role, text}
+// turns, and — on a response-complete SETTLE — pipes a JSON payload to THIS process on
+// stdin. We convert the turns to the shared exchange_batch (capture/exchanges.js), fold
+// them through the SAME spine the Claude Code hook uses (capture/capture-core.js →
+// detectors → per-session state → delta lift), and deposit the signal delta to the
+// relay's SUB-KEYED capture lane (mcp/capture-sync.js), encrypted under fp_sync_key.
+//
+// The native front-end does OS work; this owns the pairing + deposit, so the two tiers
+// (a11y, later OCR) share one Node pipeline and differ only in how turns are obtained.
+//
+// DISCARD-RAW: the turns' text is counted and dropped — nothing but signal names +
+// integers is persisted or transmitted (architecture/persona-vs-conversation-memory.md).
+// FAIL-SAFE: any error exits 0 with no output; unpaired machines still accumulate local
+// state (the mcp-local owner tier reads it), the deposit just no-ops.
+//
+// Payload (one settle = one invocation), stdin JSON:
+//   { conversation_id: string,           // STABLE per chat → per-session REPLACE (idempotent)
+//     source_surface?: string,           // default 'a11y-macos'
+//     captured_at?: string,              // ISO; default now
+//     turns: [ { role:'user'|'assistant', text:string, id?, timestamp? }, ... ] }
+
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { loadCaptureModule } from './lib/capture-home.js';
+import { isMainModule } from './lib/is-main.js';
+import { loadPairingRecord } from './phone-source.js';
+import { loadCapturePairing, CapturePairingError } from './hooks/session-end.mjs';
+import { buildCaptureDelta, depositCaptureDelta } from './capture-sync.js';
+
+const [
+  { turnsToBatch },
+  { foldBatchToSignals },
+  { deriveSourceDeviceId },
+] = await Promise.all([
+  'capture/exchanges.js',
+  'capture/capture-core.js',
+  'capture/source-id.js',
+].map(loadCaptureModule));
+
+const MCP_DIR = resolve(dirname(fileURLToPath(import.meta.url)));
+const DEFAULT_SURFACE = 'a11y-macos';
+const BUDGET_MS = 10000;
+
+// Run one a11y capture payload → deposit. Dependency-injectable for tests.
+//   payload — the native helper's stdin JSON (see header).
+//   deps    — { pairing, statePath, fetch, relayBase, now, mcpDir, env, captureModel }.
+// Returns a result record; never throws.
+export async function runA11yCapture(payload, deps = {}) {
+  const nowIso = deps.now || (payload && payload.captured_at) || new Date().toISOString();
+  const surface = (payload && payload.source_surface) || DEFAULT_SURFACE;
+
+  const turns = payload && Array.isArray(payload.turns) ? payload.turns : null;
+  if (!turns) return { deposited: false, reason: 'no-turns' };
+  const conversationId = (payload && (payload.conversation_id || payload.session_id)) || null;
+
+  const batch = turnsToBatch(turns, { sessionId: conversationId, platform: surface });
+  if (!batch.user_prompts.length) return { deposited: false, reason: 'no-exchanges' };
+
+  // Resolve the pairing whose key the draining owner can decrypt (same order as the hook:
+  // explicit override / legacy capture-pairing file / the MCP's own pairing.json). A
+  // PRESENT-but-broken capture-pairing file must not silently fall back to a different key
+  // — accumulate state locally and skip the deposit instead.
+  let pairing = deps.pairing;
+  if (pairing === undefined) {
+    try {
+      pairing = loadCapturePairing(deps.mcpDir || MCP_DIR, deps.env);
+    } catch (e) {
+      if (!(e instanceof CapturePairingError)) throw e;
+      process.stderr.write(`[phaedo capture:a11y] ${e.message}\n`);
+      const sid0 = deriveSourceDeviceId(null, surface);
+      await foldBatchToSignals(batch, { sourceId: sid0, surface, statePath: deps.statePath, sessionLocalId: conversationId, now: nowIso, captureModel: deps.captureModel, env: deps.env });
+      return { deposited: false, reason: 'capture-pairing-invalid', counted: batch.user_prompts.length };
+    }
+    if (!pairing) {
+      try { pairing = await loadPairingRecord(deps.mcpDir || MCP_DIR); } catch { pairing = null; }
+    }
+  }
+  const sourceId = deriveSourceDeviceId(pairing, surface);
+
+  const { signals } = await foldBatchToSignals(batch, {
+    sourceId, surface, statePath: deps.statePath, sessionLocalId: conversationId,
+    now: nowIso, captureModel: deps.captureModel, env: deps.env,
+  });
+  if (!signals.length) return { deposited: false, reason: 'no-signal', counted: batch.user_prompts.length };
+
+  const delta = buildCaptureDelta(signals, { sourceSurface: surface, sourceDeviceId: sourceId, capturedAt: nowIso });
+  const res = await depositCaptureDelta(pairing, delta, { ...deps, now: () => nowIso });
+  if (res && res.deposited === false && (res.status === 401 || (res.reason && /^http-/.test(String(res.reason))))) {
+    process.stderr.write(`[phaedo capture:a11y] deposit rejected (${res.status || res.reason}) — re-pair so capture can sync.\n`);
+  }
+  return { ...res, counted: batch.user_prompts.length, signals: signals.length };
+}
+
+// ── script entry (the native helper spawns `node capture-a11y.js` and pipes JSON) ──────
+const isMain = isMainModule(import.meta.url);   // symlink-safe — see lib/is-main.js
+if (isMain) {
+  const readStdin = () => new Promise((res) => {
+    let data = '';
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => res(data));
+    process.stdin.on('error', () => res(''));
+  });
+  const run = async () => {
+    let payload = {};
+    try { payload = JSON.parse(await readStdin()); } catch { /* no/bad input → no-op */ }
+    await runA11yCapture(payload);
+  };
+  const timeout = new Promise((res) => setTimeout(res, BUDGET_MS));
+  Promise.race([run().catch(() => {}), timeout])
+    .then(() => process.exit(0))
+    .catch(() => process.exit(0));   // capture must never break the helper
+}

package/capture-local.js

@@ -0,0 +1,85 @@
+// The mcp-local merge-owner tier (desktop-capture-deposit.md §4 tier 3).
+//
+// The phone-less, browser-less desktop/CLI user — the Claude Code developer, the
+// audience desktop capture was built FOR — has nobody to drain what their capture
+// hook accumulates: no phone to own the capture_to_owner lane, no extension to
+// materialize it. But the hook and this server share a machine AND a state dir:
+// the hook accumulates cumulative Path-A counters in capture/state.js
+// (~/.phaedo-mcp/capture-state.json) even when unpaired. This module folds that
+// local state into the fingerprint the server SERVES, at read time:
+//
+//   - READ-TIME OVERLAY, no persistence. The lift is a cumulative snapshot
+//     (delta-lift's idempotency contract), so re-folding on every load converges
+//     to the same result — there is nothing to store and no race to manage.
+//     The local fingerprint.json is never rewritten; discard-raw holds.
+//   - OWNER-GATED. Only when this server is the merge owner per the presence
+//     precedence (capture/owner.js): a configured pairing record means a phone
+//     owns the lane (its merged fingerprint arrives through the normal pull),
+//     so folding again here would double-count the same signal. The caller
+//     (fingerprint-source.js) applies this tier only in local, unpaired mode.
+//   - WORKS IN THE PUBLISHED PACKAGE. The capture/extraction modules load via
+//     lib/capture-home.js (repo root in dev, mcp/vendor/ in the tarball —
+//     build-package.mjs vendors the closure). Loading stays dynamic and any
+//     import/IO failure still returns the payload unchanged — the fold is an
+//     enrichment, never a gate on serving.
+//
+// Re-broadcast (§5): none needed here. If a phone is paired later, the hook's
+// normal capture_to_owner deposits carry the CUMULATIVE counts, so the phone
+// inherits this machine's full history on its first drain — and this tier stops
+// applying (owner-gated), so nothing forks.
+
+import { loadCaptureModule } from './lib/capture-home.js';
+
+// Build per-source snapshots from the hook's local capture state. Loading stays
+// try-wrapped so a broken layout (neither repo root nor vendor/) degrades to
+// "no snapshots" instead of failing the serve.
+async function localSnapshots(now) {
+  let stateMod, liftMod;
+  try {
+    stateMod = await loadCaptureModule('capture/state.js');
+    liftMod = await loadCaptureModule('extraction/delta-lift.js');
+  } catch {
+    return [];                                   // no capture home in this layout
+  }
+  const state = stateMod.loadState(stateMod.defaultStatePath());
+  const out = [];
+  for (const sourceId of Object.keys(state.surfaces || {})) {
+    const counts = stateMod.cumulativeCounts(state, sourceId);
+    const signals = liftMod.liftDeltaSignals(counts.behavioral_signals, now);
+    if (!signals.length) continue;
+    const updatedAt = state.surfaces[sourceId] && state.surfaces[sourceId].updated_at;
+    out.push({ surface: sourceId, captured_at: updatedAt || now, signals });
+  }
+  return out;
+}
+
+// Fold the local capture state into a vault payload's fingerprint and return the
+// folded payload (or the input unchanged when there is nothing to fold / the
+// modules are unavailable). Pure with respect to the input object.
+export async function foldLocalCapture(vaultPayload, { now = new Date().toISOString() } = {}) {
+  if (!vaultPayload || typeof vaultPayload !== 'object' || !vaultPayload.phaedo_fingerprint) return vaultPayload;
+  try {
+    const sources = await localSnapshots(now);
+    if (!sources.length) return vaultPayload;
+    const { mergeExtractionInto } = await loadCaptureModule('extraction/persist.js');
+    // Empty own-update: the server has no counters of its own; the combine builds
+    // the delta update entirely from the source snapshots, then the standard
+    // reconcile folds it into the fingerprint (creating layers as needed).
+    const fp = mergeExtractionInto(vaultPayload.phaedo_fingerprint, {}, now, sources);
+    return { ...vaultPayload, phaedo_fingerprint: fp };
+  } catch {
+    return vaultPayload;                         // enrichment only — never break serving
+  }
+}
+
+// Is this server the capture merge owner? Thin wrapper over capture/owner.js so
+// the precedence lives in exactly one place; an unloadable module (broken
+// layout) → not owner (the fold simply doesn't apply).
+export async function isLocalCaptureOwner(phonePaired) {
+  try {
+    const { isOwner } = await loadCaptureModule('capture/owner.js');
+    return isOwner('mcp-local', { phonePaired: !!phonePaired, extensionPresent: false });
+  } catch {
+    return false;
+  }
+}

package/capture-sync.js

@@ -0,0 +1,99 @@
+// Capture-delta transport (capture surface → relay → merge owner).
+//
+// Track A of the desktop-capture plan. The Claude Code / Cowork capture hook reads the
+// local session transcript, runs the surface-agnostic extraction engine, and deposits
+// the resulting SIGNAL DELTA (never a whole fingerprint) into the relay's
+// `capture_to_owner` mailbox lane, encrypted under fp_sync_key. Exactly one merge owner
+// (phone → extension → mcp-local, capture/owner.js) drains and reconciles it per-source
+// (capture/source-id.js), so concurrent capture on multiple surfaces accumulates instead
+// of clobbering — docs/roadmap/desktop-capture-deposit.md.
+//
+// Mirrors delegation-sync.js in trust posture, but NOT in key sensitivity: this lane is
+// drained by the PHONE, which tries each verified client's key until one decrypts, so an
+// independently-paired MCP works fine here (unlike agent_to_ext — see delegation-sync.js).
+// The relay only ever holds ciphertext; and the deposit is best-effort and
+// isolated — a transport failure never breaks the session that produced the capture.
+//
+// The lane carries a DELTA, so a deposit can never overwrite signal the owner captured
+// on its own; and per-source idempotency (source_device_id) means a re-deposit or a
+// transient two-owner overlap is a no-op, not a double-count.
+
+import { Phaedo, b64uDec } from './lib/phaedo-crypto.js';
+
+const { Kdf, Envelope } = Phaedo;
+const DEFAULT_RELAY = 'https://phaedo-relay.fly.dev';
+
+export function relayBaseFromEnv(env = process.env) {
+  return env.PHAEDO_RELAY || DEFAULT_RELAY;
+}
+
+// Build the canonical capture-delta payload from lifted signals (Q1: lift on the
+// surface — the hook runs extraction and ships §5.4 signals, not raw counters).
+//   signals — the extraction engine's signal list (source-tagged; 'delta' snapshots
+//             are idempotent on re-lift).
+export function buildCaptureDelta(signals, { sourceSurface, sourceDeviceId, capturedAt } = {}) {
+  return {
+    capture_delta_version: 'v0.1',
+    source_surface: sourceSurface || 'unknown',
+    source_device_id: sourceDeviceId || null,
+    captured_at: capturedAt || null,
+    delta: { signals: Array.isArray(signals) ? signals : [] },
+  };
+}
+
+// Wrap a capture-delta into the same envelope shape the owner's fp-mailbox drain
+// expects: ciphertext over `{ kind:'capture_delta', data: <captureDelta> }`. Returns the
+// deposit body `{ envelope }`. Pure crypto (no network) so the round-trip is testable.
+export async function buildCaptureDeposit(pairKeyB64u, captureDelta, { now = () => new Date().toISOString() } = {}) {
+  const pairKey = b64uDec(pairKeyB64u);
+  let fpSyncKey;
+  try {
+    fpSyncKey = await Kdf.deriveFpSyncKey(pairKey);
+  } finally {
+    pairKey.fill(0);
+  }
+  try {
+    const inner = { kind: 'capture_delta', data: captureDelta };
+    const plaintext = new TextEncoder().encode(JSON.stringify(inner));
+    const envelope = await Envelope.wrap(plaintext, fpSyncKey, { artifact_kind: 'capture_delta', created_at: now() });
+    plaintext.fill(0);
+    return { envelope };
+  } finally {
+    if (fpSyncKey && fpSyncKey.fill) fpSyncKey.fill(0);
+  }
+}
+
+// Deposit a capture-delta to the relay's capture_to_owner slot. Best-effort: returns
+// { deposited, ... } and never throws. `deps.fetch` is injectable for tests.
+export async function depositCaptureDelta(pairing, captureDelta, deps = {}) {
+  const fetchFn = deps.fetch || globalThis.fetch;
+  const signals = captureDelta && captureDelta.delta && Array.isArray(captureDelta.delta.signals)
+    ? captureDelta.delta.signals : [];
+  // Precise reasons so the caller can log WHY a deposit didn't happen.
+  if (!signals.length) return { deposited: false, reason: 'no-signal' };
+  if (!pairing || !pairing.pair_key) return { deposited: false, reason: 'unpaired' };
+  if (!pairing.relay_device_id) return { deposited: false, reason: 'no-relay-device-id' };
+  try {
+    const body = await buildCaptureDeposit(pairing.pair_key, captureDelta, deps);
+    // Sub-key the lane per source so a second surface on this device doesn't clobber the
+    // hook's deposit before the owner drains (desktop-capture-deposit.md). Falls back to
+    // the flat lane only if the delta somehow lacks a source id (pre-source-id builds).
+    const src = captureDelta && captureDelta.source_device_id;
+    const lane = src ? `capture_to_owner/${encodeURIComponent(src)}` : 'capture_to_owner';
+    const base = `${deps.relayBase || relayBaseFromEnv()}/fp-mailbox/${encodeURIComponent(pairing.relay_device_id)}/${lane}`;
+    // Per-device auth header (relay/auth.js). Without it the relay 401s → deposit no-ops
+    // (correct failure mode: the user re-pairs to capture the relay_device_secret).
+    const authHeader = pairing.relay_device_secret
+      ? { Authorization: `Bearer ${pairing.relay_device_id}:${pairing.relay_device_secret}` }
+      : {};
+    const res = await fetchFn(base, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...authHeader },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(deps.timeoutMs || 8000),
+    });
+    return { deposited: !!(res && res.ok), status: res && res.status, count: signals.length };
+  } catch (e) {
+    return { deposited: false, reason: String(e && e.message || e) };
+  }
+}