@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/gsd.js

@@ -26,7 +26,7 @@ import { validateBoundaryMap } from './boundary-map.js';
 import { enrichTaskGraph } from './gsd-decompose-enrich.js';
 import { buildTaskDescription } from './gsd-prompt.js';
 import { writeAll, validate as validateTaskResult, read as readBlackboard } from './gsd-blackboard.js';
-import { executeShipStep, runConsumerIssuance, ConsumerStuckError, filesOwnedConflict, toEngineUsage } from './build.js';
+import { executeShipStep, toPhaseResultOutput, runConsumerIssuance, ConsumerStuckError, filesOwnedConflict, toEngineUsage, reportUsageReceipts } from './build.js';
 import {
   ConsumerFanoutArtifacts,
   ConsumerMergeDecisionError,
@@ -175,6 +175,9 @@ export async function runGsd(featureCode, opts = {}) {
   const stratum = opts.stratum ?? new StratumMcpClient();
   const ownsStratum = !opts.stratum;
   if (ownsStratum) await stratum.connect(resolveStratumMcpConnection(cwd));
+  const receiptsMode = typeof stratum.hasTool === 'function'
+    ? await stratum.hasTool('stratum_usage_report')
+    : false;
   // COMP-GSD-4: ownership flag — release the resume lock in finally ONLY if THIS
   // process successfully claimed it (set below). Prevents (a) a non-resume run
   // from clobbering a concurrent resume's valid claim and (b) a claim-race loser
@@ -231,6 +234,7 @@ export async function runGsd(featureCode, opts = {}) {
     // docs unless context.filesChanged is provided.
     stepCtx = {
       stratum, cwd, featureCode, blueprintText, gateCommands, preMergeGate,
+      receiptsMode,
       localSpec, localSpecDigest,
       filesChanged: [],
       stuckDetector,
@@ -289,6 +293,7 @@ export async function runGsd(featureCode, opts = {}) {
       pre_merge_gate: preMergeGate,
     }, { workspaceRoot: cwd });
     const flowId = response.runId;
+    stepCtx.flowId = flowId;
     flushState(stepCtx, { flowId, phase: 'decompose' });
     emitPhaseOnce(stepCtx, 'decompose'); // COMP-GSD-7-EVENTLOG
 
@@ -518,7 +523,7 @@ async function runOneStep(response, ctx) {
           // by definition a GSD task, so timing.json + diffs/<id>.diff are written
           // for the milestone report. The build consumer path omits it (no marker),
           // so build-mode fanout stays byte-identical.
-          context: { cwd, featureCode, gsd: true, gsdTaskId: consumerItem?.id, filesChanged: ctx.filesChanged, onUsage: (usage) => recordTsAgentUsage(ctx, usage), taskResultPath },
+          context: { cwd, projectCwd: cwd, featureCode, flowId, receiptsMode: ctx.receiptsMode, gsd: true, gsdTaskId: consumerItem?.id, filesChanged: ctx.filesChanged, onUsage: (usage, meta) => recordTsAgentUsage(ctx, usage, meta), taskResultPath },
           // runAndNormalize narrates via progress.debug/warn/info/toolUse — gsd
           // has no cockpit, so a COMPLETE no-op (not just stepStart/stepDone) is
           // required or the item throws "progress.debug is not a function".
@@ -554,7 +559,14 @@ async function runOneStep(response, ctx) {
         '',
         null,
       );
-      return stratum.stepDone(flowId, step.id, { output: result }, step.dispatchToken);
+      // COMP-SHIP-CONTRACT: narrow to PhaseResult before reporting. The raw
+      // return carries `commit`/`filesChanged`/`testsAttested`, which the
+      // strict contract rejects — attempt 1 was failing on unrecognized keys and
+      // only "succeeding" because attempt 2 re-ran ship, found nothing left to
+      // stage, and returned the field-less "already committed" shape.
+      return stratum.stepDone(
+        flowId, step.id, { output: toPhaseResultOutput(result) }, step.dispatchToken,
+      );
     }
     if (step.id === 'decompose_gsd' && ctx.resumeTaskGraph) {
       ctx.lastTaskGraph = ctx.resumeTaskGraph;
@@ -565,12 +577,45 @@ async function runOneStep(response, ctx) {
 
     // D2(b): dispatch via agentRun (not runAgentText) so the TS complete
     // envelope's usage is captured and debited into the cumulative ledger.
-    const runOut = await stratum.agentRun(step.agent ?? 'claude', step.do ?? '', { cwd });
+    let runOut;
+    try {
+      runOut = await stratum.agentRun(step.agent ?? 'claude', step.do ?? '', {
+        cwd,
+        telemetry: {
+          site: 'gsd',
+          project_cwd: cwd,
+          feature_code: featureCode,
+          step_id: step.id,
+          ...(typeof step.attempt === 'number' ? { attempt: step.attempt } : {}),
+        },
+      });
+    } catch (error) {
+      if (error?.usage) {
+        await recordTsAgentUsage(ctx, error.usage, {
+          stepId: step.id,
+          source: 'main',
+          dispatchId: error.dispatchId,
+        });
+      }
+      throw error;
+    }
     const text = runOut?.text ?? '';
-    recordTsAgentUsage(ctx, runOut?.usage);
+    const directUsage = runOut?.usage && typeof runOut.usage === 'object'
+      ? {
+          ...runOut.usage,
+          dispatch_id: runOut.dispatchId,
+          model: runOut.telemetry?.model ?? runOut.usage.model ?? 'unknown',
+          ...(runOut.telemetry?.effort ? { effort: runOut.telemetry.effort } : {}),
+          duration_ms: runOut.telemetry?.durationMs ?? runOut.usage.duration_ms ?? runOut.usage.ms ?? 0,
+          ...(['reported', 'estimated'].includes(runOut.usage.usd_source)
+            ? { usd_source: runOut.usage.usd_source }
+            : {}),
+        }
+      : runOut?.usage;
+    await recordTsAgentUsage(ctx, directUsage, { stepId: step.id, source: 'main' });
     // V1: also report usage in the step_done envelope so the ENGINE debits its
     // flow budget (not just compose's cumulative ledger above).
-    const ordinaryUsage = toEngineUsage(runOut?.usage);
+    const ordinaryUsage = ctx.receiptsMode ? null : toEngineUsage(runOut?.usage);
     let result;
     try {
       result = parseJsonFromText(text);
@@ -1411,21 +1456,25 @@ const NOOP_PROGRESS = Object.freeze({
  * shape from runAndNormalize ({input_tokens, output_tokens, cost_usd,
  * duration_ms}) or the raw TS complete usage ({tokens, usd, ms}).
  */
-export function recordTsAgentUsage(ctx, usage) {
+export async function recordTsAgentUsage(ctx, usage, meta) {
   if (!usage || !ctx?.cwd || !ctx?.featureCode) return;
   const tokens = usage.tokens ?? ((usage.input_tokens ?? 0) + (usage.output_tokens ?? 0));
   const costUsd = usage.cost_usd ?? usage.usd ?? 0;
   const timeMs = usage.duration_ms ?? usage.ms ?? 0;
-  if (tokens === 0 && costUsd === 0 && timeMs === 0) return;
-  recordGsdUsage(join(ctx.cwd, '.compose'), ctx.featureCode, { tokens, costUsd, timeMs, dispatches: 1 });
+  if (tokens !== 0 || costUsd !== 0 || timeMs !== 0) {
+    recordGsdUsage(join(ctx.cwd, '.compose'), ctx.featureCode, { tokens, costUsd, timeMs, dispatches: 1 });
+  }
   // G4: remember what THIS run recorded incrementally so the terminal/budget-halt
   // fold (recordGsdUsageFromState) records only the engine-only delta, never
   // double-counting these envelope-reported invocations.
-  ctx.recordedUsage ??= { tokens: 0, costUsd: 0, dispatches: 0, timeMs: 0 };
-  ctx.recordedUsage.tokens += tokens;
-  ctx.recordedUsage.costUsd += costUsd;
-  ctx.recordedUsage.timeMs += timeMs;
-  ctx.recordedUsage.dispatches += 1;
+  if (tokens !== 0 || costUsd !== 0 || timeMs !== 0) {
+    ctx.recordedUsage ??= { tokens: 0, costUsd: 0, dispatches: 0, timeMs: 0 };
+    ctx.recordedUsage.tokens += tokens;
+    ctx.recordedUsage.costUsd += costUsd;
+    ctx.recordedUsage.timeMs += timeMs;
+    ctx.recordedUsage.dispatches += 1;
+  }
+  return reportUsageReceipts(ctx, usage, meta);
 }
 
 /**

package/lib/guard-cli.js

@@ -0,0 +1,175 @@
+import { execFile as defaultExecFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile as defaultReadFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { acquireDirLock as defaultAcquireDirLock } from './dir-lock.js';
+import { CUSTODY_TIMEOUT_MS, custodyBackend, custodySign, custodyStatus, DESCRIPTOR_LOCK_TIMEOUT_MS } from './guard-custody.js';
+import {
+  currentGeneration as defaultCurrentGeneration, descriptorIdFor, ensureSignedDescriptors as defaultEnsureSignedDescriptors,
+  enumerateRegisteredResources as defaultEnumerateRegisteredResources, prepareUnsignedCandidate as defaultPrepareUnsignedCandidate,
+  pruneGenerations as defaultPruneGenerations, verifyGeneration as defaultVerifyGeneration,
+} from './guard-descriptors.js';
+import { guardDescriptors as defaultGuardDescriptors } from '../server/stratum-client.js';
+import { runEnrol } from './guard-enrol.js';
+
+const require = createRequire(import.meta.url);
+const { parseAllowedSigners } = await import(require.resolve('@smartmemory/stratum/dist/guard/sshsig.js'));
+
+const LOCK_RELATIVE = path.join('.compose', 'data', 'locks', 'guard-descriptors');
+const LEGACY_FLAT = path.join('.compose', 'guard-upgrades.json');
+const NAMESPACE = 'stratum-guard-descriptors';
+
+function descriptorLock(workspaceRoot) { return path.join(workspaceRoot, LOCK_RELATIVE); }
+
+function makeResult(status, lines, extra = {}) { return { status, lines, ...extra }; }
+
+async function withLock(workspaceRoot, deps, operation) {
+  const release = await (deps.acquireDirLock ?? defaultAcquireDirLock)(descriptorLock(workspaceRoot), { timeoutMs: DESCRIPTOR_LOCK_TIMEOUT_MS });
+  try { return await operation(); } finally { release(); }
+}
+
+function asWorkspace(input) {
+  return typeof input === 'string' ? input : input?.workspaceRoot;
+}
+
+function manualSignLine(file) {
+  return `ssh-keygen -Y sign -f ~/.stratum/guard-signing -n ${NAMESPACE} ${file}`;
+}
+
+function signedLine(signature, count) {
+  const match = /^verified: signed by (.+) \(([^)]+)\)$/.exec(signature || '');
+  if (!match) return null;
+  return `signed by ${match[1]} (${match[2]}), ${count} descriptor(s), verified`;
+}
+
+async function descriptorCount(file, readFile) {
+  try {
+    const parsed = JSON.parse(await readFile(file, 'utf8'));
+    return Array.isArray(parsed?.descriptors) ? parsed.descriptors.length : 0;
+  } catch { return 0; }
+}
+
+/** Generate/sign descriptor generations. This returns lines; the bin owns stdout. */
+export async function runGuardDescriptors(input, deps = {}) {
+  const workspaceRoot = asWorkspace(input);
+  if (!workspaceRoot) throw new Error('workspaceRoot is required');
+  try {
+    return await withLock(workspaceRoot, deps, async () => {
+      const backend = (deps.custodyBackend ?? custodyBackend)();
+      const enumerate = deps.enumerateRegisteredResources ?? defaultEnumerateRegisteredResources;
+      const resources = await enumerate(workspaceRoot);
+      const needChecksums = resources.map((resource) => resource.from_checksum ?? resource.fromChecksum).filter(Boolean);
+      const verifier = deps.guardDescriptors ?? defaultGuardDescriptors;
+      const ensured = await (deps.ensureSignedDescriptors ?? defaultEnsureSignedDescriptors)({
+        workspaceRoot,
+        needChecksums,
+        custody: { sign: (request) => (deps.custodySign ?? custodySign)(request) },
+        verifier,
+        enumerate,
+      });
+      if (ensured.status === 'refused') {
+        // Only the plain "no custody available" refusal falls back to the manual
+        // unsigned-candidate path. Any other refusal (e.g. an existing generation
+        // whose signature does not verify) must be returned as-is — falling back
+        // here would print a `ssh-keygen -Y sign` line targeting a path that
+        // already carries an invalid `.sig`, which is exactly the "sign over an
+        // invalid generation" path S1 forbids.
+        if (backend === 'none' && ensured.message === 'no signing custody on this platform') {
+          const candidate = await (deps.prepareUnsignedCandidate ?? defaultPrepareUnsignedCandidate)(workspaceRoot, { enumerate });
+          return makeResult('manual', [manualSignLine(candidate.path)], { path: candidate.path, sha: candidate.sha });
+        }
+        return makeResult('refused', [ensured.message, ensured.hint].filter(Boolean), ensured);
+      }
+      if (ensured.status === 'fresh') return makeResult('fresh', [`fresh: ${ensured.path}`], ensured);
+      const inspected = await verifier(ensured.path);
+      const verdict = signedLine(inspected?.signature, await descriptorCount(ensured.path, deps.readFile ?? defaultReadFile));
+      if (!verdict || inspected?.status !== 'ok' || inspected?.group_or_world_writable !== false) {
+        return makeResult('refused', [`signature did not verify: ${inspected?.signature || 'no verifier verdict'}`], { code: 'upgrade_descriptor_unavailable', path: ensured.path });
+      }
+      return makeResult('signed', [verdict], ensured);
+    });
+  } catch (error) {
+    return makeResult('refused', [error?.message || String(error)], { code: 'upgrade_descriptor_unavailable' });
+  }
+}
+
+/** Explicit signing uses the same safe generation path as descriptors. */
+export async function runGuardSign(input, deps = {}) {
+  return runGuardDescriptors(input, deps);
+}
+
+export async function runGuardEnrol(options = {}, deps = {}) {
+  return runEnrol(options, deps);
+}
+
+function runCommand(execFile, file, args, options) {
+  return new Promise((resolve) => {
+    try {
+      execFile(file, args, options, (error, stdout = '', stderr = '') => resolve({ error, stdout, stderr }));
+    } catch (error) { resolve({ error, stdout: '', stderr: '' }); }
+  });
+}
+
+async function coverage(workspaceRoot, generation, deps) {
+  const enumerate = deps.enumerateRegisteredResources ?? defaultEnumerateRegisteredResources;
+  const readFile = deps.readFile ?? defaultReadFile;
+  try {
+    const resources = await enumerate(workspaceRoot);
+    if (!generation) return { covered: 0, total: resources.length };
+    const parsed = JSON.parse(await readFile(generation.file, 'utf8'));
+    const ids = new Set((parsed.descriptors || []).map((item) => item?.id));
+    const covered = resources.filter((resource) => {
+      const checksum = resource.from_checksum ?? resource.fromChecksum;
+      return (parsed.descriptors || []).some((item) => item?.from_checksum === checksum)
+        || ids.has(descriptorIdFor(checksum, resource.mode));
+    }).length;
+    return { covered, total: resources.length };
+  } catch (error) { return { error: error?.message || String(error) }; }
+}
+
+/** Read-only signing diagnostics. `--prune` is deliberately handled by the caller first. */
+export async function signingStatusLines(input, deps = {}) {
+  const workspaceRoot = asWorkspace(input);
+  if (!workspaceRoot) throw new Error('workspaceRoot is required');
+  const status = await (deps.custodyStatus ?? custodyStatus)();
+  const current = await (deps.currentGeneration ?? defaultCurrentGeneration)(workspaceRoot);
+  let verdict = null;
+  if (current) {
+    try { verdict = await (deps.verifyGeneration ?? defaultVerifyGeneration)(workspaceRoot, current.file, deps.guardDescriptors ?? defaultGuardDescriptors); } catch (error) { verdict = { signature: `NOT VERIFIED: ${error.message}`, verified: false }; }
+  }
+  // Coverage probes every feature dir x mode through the stratum CLI (76 s and
+  // ~370 spawns on the compose repo itself, measured 2026-09-06) — opt-in.
+  const covered = deps.coverage ? await coverage(workspaceRoot, current, deps) : null;
+  const git = await runCommand(deps.execFile ?? defaultExecFile, 'git', ['status', '--porcelain', '--', '.compose/guard-upgrades'], { cwd: workspaceRoot, timeout: CUSTODY_TIMEOUT_MS });
+  const publicSigner = status.publicKeyLine ? (() => {
+    try { return parseAllowedSigners(`status ${status.publicKeyLine.trim()}\n`)[0]?.fingerprint ?? null; } catch { return null; }
+  })() : null;
+  const lines = [
+    'signing:',
+    `  backend: ${status.backend}`,
+    `  installed: ${status.installed ? 'yes' : 'no'}`,
+    `  rule: ${status.rule}`,
+    `  presence: ${status.presence}`,
+    `  enrolled fingerprint: ${publicSigner || 'absent'}`,
+    `  current generation: ${current ? current.sha : 'absent'}`,
+    `  signature: ${current ? (verdict?.signature || 'NOT VERIFIED') : 'absent'}`,
+    `  coverage: ${covered === null ? 'skipped (pass --coverage)' : covered.error ? `unknown (${covered.error})` : `${covered.covered}/${covered.total}`}`,
+    `  generations committed: ${!git.error && !String(git.stdout).trim() ? 'yes' : 'no'}`,
+    `  legacy flat pair: ${existsSync(path.join(workspaceRoot, LEGACY_FLAT)) && existsSync(path.join(workspaceRoot, `${LEGACY_FLAT}.sig`)) ? 'present — delete after committing generations' : 'absent'}`,
+    `  cached admin credential: ${status.cachedCredential}`,
+  ];
+  for (const detail of status.detail || []) lines.push(`  detail: ${detail}`);
+  return makeResult('ok', lines, { custodyStatus: status, current, verdict, coverage: covered });
+}
+
+export async function pruneGuardGenerations(input, deps = {}) {
+  const workspaceRoot = asWorkspace(input);
+  try {
+    const result = await withLock(workspaceRoot, deps, () => (deps.pruneGenerations ?? defaultPruneGenerations)(workspaceRoot));
+    return makeResult('ok', result.removed.length ? result.removed.map((sha) => `pruned: ${sha}`) : ['pruned: none'], result);
+  } catch (error) {
+    return makeResult('refused', [error?.message || String(error)], { code: 'upgrade_descriptor_unavailable' });
+  }
+}

package/lib/guard-custody.js

@@ -0,0 +1,141 @@
+import { execFile as defaultExecFile } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import os from 'node:os';
+
+export const GUARD_DIR = '/Library/Compose/guard';
+export const SIGNER_PATH = '/Library/Compose/guard/sign';
+export const PUBKEY_PATH = '/Library/Compose/guard/signing-key.pub';
+export const PRIVATE_DIR = '/Library/Compose/guard/private';
+export const SUDOERS_PATH = '/private/etc/sudoers.d/compose-guard';
+export const SUDO_LOCAL_PATH = '/private/etc/pam.d/sudo_local';
+export const CUSTODY_TIMEOUT_MS = 120_000;
+export const DESCRIPTOR_LOCK_TIMEOUT_MS = 150_000;
+export const HINT_ENROL = 'compose guard enrol';
+export const HINT_APPROVE = 'approve the Touch ID prompt; if none appeared, run compose guard sign from a terminal on this Mac';
+
+/** The only environment the root-owned signer may inherit. */
+export const SUDO_ENV = () => ({
+  PATH: '/usr/bin:/bin',
+  HOME: os.homedir(),
+  USER: os.userInfo().username,
+  LANG: 'C',
+});
+
+let testBackend = null;
+
+/** The selected custody backend. Test injection wins over the host platform. */
+export function custodyBackend() {
+  if (testBackend !== null) return typeof testBackend === 'string' ? testBackend : (testBackend.backend ?? 'test');
+  return process.platform === 'darwin' ? 'sudo' : 'none';
+}
+
+/** Test-only backend injection. Kept unavailable to shipped callers. */
+export function _testOnly_setCustodyBackend(backend) {
+  if (process.env.NODE_ENV !== 'test') {
+    throw new Error('_testOnly_setCustodyBackend is only available when NODE_ENV=test');
+  }
+  testBackend = backend ?? null;
+}
+
+function firstLine(value, fallback) {
+  return String(value || '').split(/\r?\n/, 1)[0] || fallback;
+}
+
+function refusal(code, message, hint) {
+  return { ok: false, code, message, hint };
+}
+
+function isNotApproved(error, stderr) {
+  return error?.killed || error?.code === 'ETIMEDOUT'
+    || /terminal is required|Sorry, try again|authentication failed|timed out/i.test(String(stderr || error?.message || ''));
+}
+
+function spawnWithInput(execFile, file, args, options, bytes) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (error, stdout, stderr) => {
+      if (settled) return;
+      settled = true;
+      resolve({ error, stdout: stdout || '', stderr: stderr || '' });
+    };
+    try {
+      const child = execFile(file, args, options, done);
+      if (child?.stdin) {
+        try { child.stdin.end(bytes); } catch { /* callback maps the failure */ }
+      }
+      child?.on?.('error', (error) => done(error, '', ''));
+    } catch (error) {
+      done(error, '', '');
+    }
+  });
+}
+
+/** Ask the selected custody backend to sign exact in-memory bytes. */
+export async function custodySign({ bytes, namespace }, deps = {}) {
+  if (testBackend && typeof testBackend === 'object' && typeof testBackend.sign === 'function') {
+    return testBackend.sign({ bytes, namespace });
+  }
+  if (custodyBackend() !== 'sudo') {
+    return refusal('upgrade_descriptor_unavailable', 'no signing custody on this platform', HINT_ENROL);
+  }
+
+  const { error, stdout, stderr } = await spawnWithInput(
+    deps.execFile ?? defaultExecFile,
+    '/usr/bin/sudo',
+    ['-k', SIGNER_PATH, namespace],
+    { env: SUDO_ENV(), timeout: CUSTODY_TIMEOUT_MS, maxBuffer: 1 << 20 },
+    bytes,
+  );
+  if (!error) return { ok: true, armored: stdout };
+  if (isNotApproved(error, stderr)) {
+    return refusal('signature_not_approved', firstLine(stderr || error.message, 'signature approval was not completed'), HINT_APPROVE);
+  }
+  return refusal('upgrade_descriptor_unavailable', firstLine(stderr || error.message, 'signer failed'), HINT_ENROL);
+}
+
+async function commandStatus(args, deps = {}) {
+  const { error, stdout, stderr } = await spawnWithInput(
+    deps.execFile ?? defaultExecFile, '/usr/bin/sudo', args, { env: SUDO_ENV(), timeout: 5_000 }, Buffer.alloc(0),
+  );
+  return { code: error?.code ?? 0, stdout, stderr, error };
+}
+
+async function expectedFile(file, mode) {
+  try {
+    const info = await stat(file);
+    return info.uid === 0 && (info.mode & 0o777) === mode;
+  } catch { return false; }
+}
+
+/** Report separately what can be observed about the sudo installation. */
+export async function custodyStatus(deps = {}) {
+  if (testBackend && typeof testBackend === 'object' && typeof testBackend.status === 'function') {
+    return testBackend.status();
+  }
+  const backend = custodyBackend();
+  if (backend !== 'sudo') {
+    return { backend, installed: false, rule: 'absent', presence: 'unknown', cachedCredential: 'unknown', publicKeyLine: null, detail: ['no signing custody on this platform'] };
+  }
+
+  const [guard, privateDir, signer, pubkey, sudoers, sudoLocal] = await Promise.all([
+    expectedFile(GUARD_DIR, 0o755), expectedFile(PRIVATE_DIR, 0o700), expectedFile(SIGNER_PATH, 0o755),
+    expectedFile(PUBKEY_PATH, 0o644), expectedFile(SUDOERS_PATH, 0o440), readFile(SUDO_LOCAL_PATH, 'utf8').catch(() => ''),
+  ]);
+  const detail = [];
+  const listed = await commandStatus(['-n', '-l', SIGNER_PATH], deps);
+  const rule = listed.code === 0 ? 'present'
+    : /password is required/i.test(listed.stderr) ? 'unknown' : 'absent';
+  if (rule === 'unknown') detail.push('sudo requires authentication to list');
+  const cached = await commandStatus(['-n', '-v'], deps);
+  const cachedCredential = cached.code === 0 ? 'live' : cached.code === 1 ? 'none' : 'unknown';
+  const touchId = /^\s*auth\s+sufficient\s+pam_tid\.so/m.test(sudoLocal);
+  const remote = Boolean(process.env.SSH_CONNECTION || process.env.TMUX);
+  const presence = remote ? 'unlikely' : touchId ? 'likely' : 'unknown';
+  if (remote) detail.push('SSH_CONNECTION or TMUX prevents a reliable Touch ID prompt');
+  if (!touchId) detail.push('sudo_local has no active pam_tid line');
+  let publicKeyLine = null;
+  try { publicKeyLine = (await readFile(PUBKEY_PATH, 'utf8')).trim() || null; } catch { /* reported by installed */ }
+  return {
+    backend, installed: guard && privateDir && signer && pubkey && sudoers, rule, presence, cachedCredential, publicKeyLine, detail,
+  };
+}