refactor(snapshot): clean snapshot ownership

Author: thymikee

fallow-baselines/health.json

@@ -580,7 +580,6 @@
     "src/compat/maestro/support.ts:high impact",
     "src/daemon/session-routing.ts:high impact",
     "src/daemon/handlers/session-state.ts:complexity",
-    "src/snapshot/snapshot-processing.ts:high impact",
     "src/commands/cli-grammar/common.ts:high impact",
     "src/daemon/snapshot-presentation/tree.ts:high impact",
     "src/utils/success-text.ts:high impact",

packages/contracts/src/android-snapshot-quality.test.ts

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import {
+  ANDROID_CONTENT_RECOVERY_REASONS,
+  isAndroidContentRecoveryReason,
+  isUnreadableCaptureContentError,
+} from './facades/platform.ts';
+
+test('Android content-recovery reasons are a single guarded taxonomy', () => {
+  assert.deepEqual(ANDROID_CONTENT_RECOVERY_REASONS, [
+    'empty-helper-output',
+    'system-window-only',
+    'content-poor-app-window',
+  ]);
+  for (const reason of ANDROID_CONTENT_RECOVERY_REASONS) {
+    assert.equal(isAndroidContentRecoveryReason(reason), true);
+    assert.equal(
+      isUnreadableCaptureContentError({ details: { androidSnapshotHelperFailureReason: reason } }),
+      true,
+    );
+  }
+  assert.equal(isAndroidContentRecoveryReason('helper-timeout'), false);
+  assert.equal(
+    isUnreadableCaptureContentError({
+      details: { androidSnapshotHelperFailureReason: 'helper-timeout' },
+    }),
+    false,
+  );
+});

packages/contracts/src/android-snapshot-quality.ts

@@ -0,0 +1,36 @@
+/**
+ * Android helper content verdicts. The helper captured a tree successfully, but the
+ * current screen did not contain enough readable application content to use as a
+ * snapshot. Keep the enumeration here so the producer, waits, and replay recovery
+ * cannot grow different retry taxonomies.
+ */
+export const ANDROID_CONTENT_RECOVERY_REASONS = [
+  'empty-helper-output',
+  'system-window-only',
+  'content-poor-app-window',
+] as const;
+
+export type AndroidContentRecoveryReason = (typeof ANDROID_CONTENT_RECOVERY_REASONS)[number];
+
+const ANDROID_CONTENT_RECOVERY_REASON_SET: ReadonlySet<string> = new Set(
+  ANDROID_CONTENT_RECOVERY_REASONS,
+);
+
+export function isAndroidContentRecoveryReason(
+  value: unknown,
+): value is AndroidContentRecoveryReason {
+  return typeof value === 'string' && ANDROID_CONTENT_RECOVERY_REASON_SET.has(value);
+}
+
+/**
+ * True when a thrown Android capture failure is a content verdict rather than a
+ * mechanism failure. Wait and replay polling may ride out these states; helper
+ * timeouts, adb failures, and missing artifacts remain fail-fast.
+ */
+export function isUnreadableCaptureContentError(error: unknown): boolean {
+  if (!error || typeof error !== 'object') return false;
+  const details = (error as { details?: unknown }).details;
+  if (!details || typeof details !== 'object') return false;
+  const reason = (details as Record<string, unknown>).androidSnapshotHelperFailureReason;
+  return isAndroidContentRecoveryReason(reason);
+}

packages/contracts/src/facades/platform.ts

@@ -12,6 +12,12 @@ export type {
   AndroidInputOwnership,
   AndroidInputOwnershipSource,
 } from '../android-input-ownership.ts';
+export {
+  ANDROID_CONTENT_RECOVERY_REASONS,
+  isAndroidContentRecoveryReason,
+  isUnreadableCaptureContentError,
+} from '../android-snapshot-quality.ts';
+export type { AndroidContentRecoveryReason } from '../android-snapshot-quality.ts';
 export {
   ANDROID_SYSTEM_CHROME_PACKAGE,
   hasAndroidSystemChromeProvenance,

packages/kernel/src/snapshot.ts

@@ -3,8 +3,8 @@
  * The daemon renders it; it never re-derives degradation from node shapes.
  *
  * Defined here (the foundational snapshot type module) rather than in
- * snapshot-quality.ts so SnapshotNode can reference it without a cyclic import;
- * snapshot-quality.ts (the validation logic) re-exports it for existing callers.
+ * snapshot-quality/verdict.ts so SnapshotNode can reference it without a cyclic import;
+ * snapshot-quality/verdict.ts owns the validation logic.
  */
 /**
  * Which capture STRATEGY produced a snapshot, within one platform's plan —
@@ -175,7 +175,7 @@ export type SnapshotState = {
   /**
    * Android: the capture is an occluding system surface (notification shade, quick settings)
    * rather than app content. Consumers that surface this tree to the agent must disclose the
-   * occlusion (see snapshot/system-surface-disclosure.ts).
+   * occlusion (see core/android-system-surface-disclosure.ts).
    */
   systemSurfaceOnly?: boolean;
 };

scripts/__tests__/help-conformance-sample-producers.ts

@@ -33,8 +33,8 @@ import {
 import type { ConnectVerification } from '../../src/cli/connection/connect-provider-adapters.ts';
 import type { RemoteConnectionState } from '../../src/remote/remote-connection-state.ts';
 import { AppError, normalizeError } from '@agent-device/kernel/errors';
-import type { SnapshotQualityVerdict } from '../../src/snapshot/snapshot-quality.ts';
-import { renderSnapshotQualityWarnings } from '../../src/snapshot/snapshot-quality.ts';
+import type { SnapshotQualityVerdict } from '@agent-device/kernel/snapshot';
+import { renderSnapshotQualityWarnings } from '../../src/snapshot-quality/warnings.ts';
 import { formatSnapshotText, printHumanError } from '../../src/utils/output.ts';
 
 // The production renderer behind each captured sample in

scripts/help-conformance-sample-outputs.mjs

@@ -72,7 +72,7 @@ hint: The UI kept changing for the whole settle budget (animation, carousel, or
 
 // Recovered snapshot: the private-ax fallback fired but still exposed
 // actionable refs. Warning wording is renderSnapshotQualityWarnings
-// (src/snapshot/snapshot-quality.ts); lines are the structured snapshot
+// (src/snapshot-quality/warnings.ts); lines are the structured snapshot
 // renderer (src/utils/output.ts formatSnapshotText).
 export const PRIVATE_AX_RECOVERY_SAMPLE = {
   command: 'agent-device snapshot -i',

scripts/layering/model.test.ts

@@ -152,6 +152,7 @@ test('classifyZone separates the ranked spine from intentionally-unranked zones'
   // forbids daemon/ from importing commands/ so the files that wire them cannot be ranked.
   assert.equal(classifyZone('mcp'), 'ranked');
   assert.equal(classifyZone('snapshot'), 'ranked');
+  assert.equal(classifyZone('snapshot-quality'), 'ranked');
   // A zone that is neither ranked nor listed peripheral must be flagged, never
   // silently treated as back-edge-free.
   assert.equal(classifyZone('not-a-real-zone'), 'unclassified');

scripts/layering/model.ts

@@ -43,6 +43,7 @@ const TARGET_DAG_RANK = new Map([
   ['screenshot-diff', 1],
   ['selectors', 1],
   ['snapshot', 1],
+  ['snapshot-quality', 1],
   ['utils', 1],
   ['core', 2],
   ['cli-schema', 3],

src/commands/capture/runtime/snapshot.ts

@@ -19,9 +19,9 @@ import {
   buildSnapshotDiff,
   countSnapshotComparableLines,
 } from '../../../snapshot/snapshot-diff.ts';
-import { renderSnapshotQualityWarnings } from '../../../snapshot/snapshot-quality.ts';
+import { renderSnapshotQualityWarnings } from '../../../snapshot-quality/warnings.ts';
 import { buildSnapshotVisibility } from '../../../snapshot/snapshot-visibility.ts';
-import { ANDROID_SYSTEM_SURFACE_DISCLOSURE } from '../../../snapshot/system-surface-disclosure.ts';
+import { ANDROID_SYSTEM_SURFACE_DISCLOSURE } from '../../../core/android-system-surface-disclosure.ts';
 import { formatReactNativeOverlayWarning } from '../../react-native/overlay.ts';
 import { now } from '../../runtime-common.ts';
 import type {