diff --git a/.github/native/product_failure_diagnosis.py b/.github/native/product_failure_diagnosis.py
new file mode 100644
index 000000000..1cda3f244
--- /dev/null
+++ b/.github/native/product_failure_diagnosis.py
@@ -0,0 +1,264 @@
+"""Read existing failed-sample files; export fixed observations, never raw text."""
+from itertools import islice
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import unicodedata
+import xml.etree.ElementTree as ET
+
+FILE_LIMIT = 1024 * 1024
+METRO_LIMIT = 256 * 1024
+SNAPSHOT_LIMIT = 8
+NODE_LIMIT = 10000
+FLOWS = ('product_first_wallet.yaml', 'product_retry.yaml')
+IDS = {'btn_skip': 'onboarding_skip', 'view_startNewTile': 'start_new_tile',
+ 'view_recoverTile': 'recover_tile', 'btn_AppSettingsIcon': 'app_settings'}
+TEXT = {'Start New': 'start_new_text', 'Welcome to Bitcoin Keeper': 'welcome',
+ 'Create a passcode': 'create_passcode', 'Confirm your passcode': 'confirm_passcode',
+ 'Enter your passcode': 'login', 'Welcome Back': 'welcome_back',
+ 'Unable to check your passcode. Please try again.': 'credential_error', 'Retry': 'retry',
+ 'Dismiss': 'dismiss_control', 'Minimize': 'minimize_control',
+ 'Allow': 'allow_control', "Don't Allow": 'dont_allow_control',
+ 'Don’t Allow': 'dont_allow_control'}
+LOGBOX = ('Console Error', 'Uncaught Error', 'Syntax Error', 'Render Error', 'Failed to compile')
+FLAGS = tuple(dict.fromkeys((*IDS.values(), *TEXT.values(), 'logbox_error_header',
+ 'logbox_warning_header', 'logbox_counter', 'logbox_controls', 'logbox_syntax_footer',
+ 'notification_prompt_phrase', 'notification_permission_controls')))
+SELECTORS = {**{f'id: {key}': value for key, value in IDS.items()},
+ **{f'"{key}"': value for key, value in TEXT.items()
+ if value in ('create_passcode', 'confirm_passcode', 'login', 'retry')}}
+FAULTS = {'JS_TYPE_ERROR': r'\bTypeError\b', 'JS_REFERENCE_ERROR': r'\bReferenceError\b',
+ 'JS_SYNTAX_ERROR': r'\bSyntaxError\b', 'MODULE_RESOLUTION_ERROR': r'Unable to resolve module|\bUnableToResolveError\b',
+ 'TRANSFORM_ERROR': r'\bTransformError\b', 'APP_NOT_REGISTERED': r'has not been registered',
+ 'NATIVE_MODULE_UNAVAILABLE': r'TurboModuleRegistry\.getEnforcing|requireNativeComponent|native module cannot be null',
+ 'MEMORY_EXHAUSTION': r'out of memory|heap limit|heap out of memory',
+ 'TRANSPORT_ERROR': r'\b(?:EADDRINUSE|ECONNREFUSED|ECONNRESET)\b',
+ 'FILESYSTEM_ERROR': r'\b(?:ENOENT|EACCES|ENOSPC)\b'}
+
+
+def regular(path, root):
+ root, path = Path(root), Path(path)
+ if root.is_symlink() or not root.is_dir() or not path.resolve().is_relative_to(root.resolve()):
+ raise ValueError()
+ for part in (path, *path.parents):
+ if part.is_symlink():
+ raise ValueError()
+ if part == root:
+ break
+ info = path.stat()
+ if not stat.S_ISREG(info.st_mode):
+ raise ValueError()
+ return info
+
+
+def read(path, root):
+ regular(path, root)
+ with path.open('rb') as source:
+ payload = source.read(FILE_LIMIT + 1)
+ if len(payload) > FILE_LIMIT:
+ raise ValueError()
+ return payload
+
+
+def unique_object(pairs):
+ result = {}
+ for key, value in pairs:
+ if key in result:
+ raise ValueError()
+ result[key] = value
+ return result
+
+
+def junit(directory, flow):
+ result = {'state': 'UNKNOWN', 'failed_selector': None, 'failure_kind': None}
+ try:
+ if flow not in FLOWS:
+ return result
+ payload = read(directory / 'junit.xml', directory).decode('utf-8-sig')
+ if ' SNAPSHOT_LIMIT
+ for path in sorted(paths[:SNAPSHOT_LIMIT]):
+ try:
+ pending = [(json.loads(read(path, directory), object_pairs_hook=unique_object), 0)]
+ count, found = 0, dict.fromkeys(FLAGS, False)
+ while pending:
+ node, depth = pending.pop()
+ count += 1
+ if count > NODE_LIMIT or depth > 128 or not isinstance(node, dict):
+ raise ValueError()
+ attrs, children = node.get('attributes', {}), node.get('children', [])
+ if (not isinstance(attrs, dict) or not isinstance(children, list) or
+ any(not isinstance(key, str) or not isinstance(value, str) for key, value in attrs.items())):
+ raise ValueError()
+ resource = attrs.get('resource-id')
+ if isinstance(resource, str):
+ resource = resource.removeprefix('io.hexawallet.keeper.development:id/')
+ if resource in IDS:
+ found[IDS[resource]] = True
+ for key in ('text', 'accessibilityText', 'title', 'value'):
+ value = attrs.get(key)
+ if not isinstance(value, str):
+ continue
+ value = value.strip()
+ if value in TEXT:
+ found[TEXT[value]] = True
+ found['logbox_error_header'] |= value in LOGBOX
+ found['logbox_warning_header'] |= value == 'Console Warning'
+ found['logbox_counter'] |= bool(re.fullmatch(r'Log [1-9]\d* of [1-9]\d*', value))
+ found['logbox_syntax_footer'] |= value == 'This error cannot be dismissed.'
+ found['notification_prompt_phrase'] |= 'would like to send you notifications' in value.lower()
+ pending.extend((child, depth + 1) for child in children)
+ found['logbox_controls'] = found['dismiss_control'] and found['minimize_control']
+ found['notification_permission_controls'] = (found['notification_prompt_phrase'] and
+ found['allow_control'] and found['dont_allow_control'])
+ result['snapshot_count'] += 1
+ result['node_count'] += count
+ observed = {key: observed[key] or found[key] for key in FLAGS}
+ except (OSError, ValueError, TypeError, RecursionError):
+ result['rejected_snapshots'] += 1
+ if result['snapshot_count']:
+ complete = not result['rejected_snapshots'] and not result['snapshot_limit_exceeded']
+ result['state'] = 'COMPLETE' if complete else 'PARTIAL'
+ result['flags'] = {key: value if value or complete else None for key, value in observed.items()}
+ except OSError:
+ pass
+ return result
+
+
+class MetroBinding:
+ def __init__(self, metro):
+ count = len(metro.events)
+ if (metro.phase != 'product' or not count or metro.events[-1].get('phase') != 'product' or
+ not any(child is metro.process for child in metro.owned)):
+ raise ValueError()
+ self.process, self.count, self.root = metro.process, count, Path(metro.private)
+ self.path = self.root / ('metro-%02d.log' % count)
+ regular(self.path, self.root)
+ with self.path.open('rb') as source:
+ info = os.fstat(source.fileno())
+ self.identity, self.offset = (info.st_dev, info.st_ino), info.st_size
+ source.seek(max(0, self.offset - 1))
+ self.partial_start = bool(self.offset and source.read(1) != b'\n')
+
+
+def bind_metro(metro):
+ try:
+ return MetroBinding(metro)
+ except Exception:
+ return None
+
+
+def metro_window(metro, binding):
+ result = {'state': 'UNKNOWN', 'scope': 'Bound product-sample console window; markers are not cause or request proof.',
+ 'process_state': 'UNKNOWN', 'exit_code': None}
+ try:
+ if (binding is None or metro.phase != 'product' or metro.process is not binding.process or
+ len(metro.events) != binding.count or metro.events[-1].get('phase') != 'product' or
+ Path(metro.private) != binding.root or not any(child is binding.process for child in metro.owned)):
+ return result
+ try:
+ code = binding.process.poll()
+ if code is None:
+ result['process_state'] = 'ALIVE'
+ elif type(code) is int:
+ result.update(process_state='EXITED', exit_code=code)
+ except Exception:
+ pass
+ info = regular(binding.path, binding.root)
+ if (info.st_dev, info.st_ino) != binding.identity or info.st_size < binding.offset:
+ return result
+ end, start = info.st_size, max(binding.offset, info.st_size - METRO_LIMIT)
+ with binding.path.open('rb') as source:
+ current = source.fileno()
+ opened = os.fstat(current)
+ if (opened.st_dev, opened.st_ino) != binding.identity:
+ return result
+ source.seek(start)
+ payload = source.read(end - start)
+ after = os.fstat(current)
+ current = regular(binding.path, binding.root)
+ if (len(payload) != end - start or min(after.st_size, current.st_size) < end or
+ (current.st_dev, current.st_ino) != binding.identity):
+ return result
+ partial_start = binding.partial_start or start > binding.offset
+ partial_end = bool(payload and not payload.endswith(b'\n'))
+ if partial_end:
+ payload = payload[:payload.rfind(b'\n') + 1] if b'\n' in payload else b''
+ if partial_start:
+ payload = payload.split(b'\n', 1)[1] if b'\n' in payload else b''
+ grew = max(after.st_size, current.st_size) > end
+ result.update(state='PARTIAL' if partial_start or partial_end or start > binding.offset or grew else 'COMPLETE',
+ bytes_appended=end - binding.offset, bytes_read=end - start, bytes_scanned=len(payload),
+ input_truncated=start > binding.offset, partial_start=partial_start, partial_end=partial_end,
+ growth_detected=grew, complete_lines=payload.count(b'\n'))
+ categories, headers, unknown, valid, invalid = set(), 0, 0, 0, 0
+ for raw in payload.split(b'\n')[:-1]:
+ try:
+ line = raw.removesuffix(b'\r').decode('utf-8')
+ line = re.sub(r'\x1b\[[0-9;]*[A-Za-z]', '', line)
+ if any(unicodedata.category(char) in ('Cc', 'Zl', 'Zp') and char != '\t' for char in line):
+ raise ValueError()
+ except (UnicodeError, ValueError):
+ invalid += 1
+ continue
+ valid += 1
+ line = line.strip()
+ if not re.match(r'^(?:ERROR\b|FATAL ERROR:|\w*Error:|Unable to resolve module)', line, re.IGNORECASE):
+ continue
+ headers += 1
+ found = [key for key, pattern in FAULTS.items() if re.search(pattern, line, re.IGNORECASE)]
+ categories.update(found)
+ unknown += not bool(found)
+ if invalid:
+ result['state'] = 'PARTIAL' if valid else 'UNKNOWN'
+ result.update(error_headers=headers, unclassified_error_headers=unknown,
+ valid_records=valid, invalid_records=invalid,
+ fault_categories=[key for key in FAULTS if key in categories])
+ except Exception:
+ pass
+ return result
+
+
+def collect(directory, flow, metro, binding=None):
+ directory = Path(directory)
+ return {'scope': 'Failed-sample files and bound owned Metro only; observations do not prove current visibility, route, tap delivery or cause.',
+ 'junit': junit(directory, flow), 'hierarchy': hierarchy(directory),
+ 'product_metro': metro_window(metro, binding)}
diff --git a/.github/native/product_measurements.py b/.github/native/product_measurements.py
index f89c5a118..e2950aca0 100644
--- a/.github/native/product_measurements.py
+++ b/.github/native/product_measurements.py
@@ -32,7 +32,7 @@
def native_module(name):
- if name not in ('product_metro', 'product_credential_acceptance',
+ if name not in ('product_metro', 'product_failure_diagnosis', 'product_credential_acceptance',
'product_history_acceptance', 'product_vault_acceptance'):
raise RuntimeError('PRODUCT_UI_FIXED_COMPANION_REQUIRED')
spec = importlib.util.spec_from_file_location(name, Path(__file__).with_name(name + '.py'))
@@ -66,6 +66,22 @@ def android_failure_observation(private, device):
return {'status': 'UNAVAILABLE', 'scope': scope}
+def prepare_failure_observation(metro):
+ try:
+ module = native_module('product_failure_diagnosis')
+ return module, module.bind_metro(metro)
+ except Exception:
+ return None
+
+
+def sample_failure_observation(private, flow, metro, observer):
+ try:
+ module, binding = observer or (native_module('product_failure_diagnosis'), None)
+ return module.collect(private, flow, metro, binding)
+ except Exception:
+ return {'status': 'UNKNOWN', 'scope': 'Failed-sample observation unavailable; original failure retained.'}
+
+
class Receipt:
"""Fixed vocabulary and numbers only; never store a request body/identifier."""
def __init__(self):
@@ -375,8 +391,11 @@ def save():
else:
h.command(['adb', '-s', device, 'install', '-r', artifact], 'Install exact product UI APK', timeout=120)
h.command(['adb', '-s', device, 'shell', 'pm', 'clear', app], 'Clear only disposable development app')
+ flow = 'product_retry.yaml' if retry_fixture else 'product_first_wallet.yaml'
+ observer = None
try:
installed_before = key_companion.installed_proof(h, device)
+ observer = prepare_failure_observation(metro)
h.command([data['maestro']['binary'], '--device', device, 'test',
'--env', 'APP_ID=' + app,
'--env', 'EXPECTED_INSTALLED_REGEX=' + expected_version['installed_regex'],
@@ -384,8 +403,7 @@ def save():
'--flatten-debug-output',
'--debug-output', str(output), '--test-output-dir', str(output),
'--format', 'junit', '--output', str(report),
- '.github/native/product_retry.yaml' if retry_fixture else
- '.github/native/product_first_wallet.yaml'],
+ '.github/native/' + flow],
'Full-product controlled disconnect and Retry fixture' if retry_fixture else
'Full-product first-wallet and relaunch UI sample', timeout=600, error_details=False)
h.successful_junit(report)
@@ -403,6 +421,7 @@ def save():
result['samples'].append(outcome)
except Exception:
outcome = receipt.snapshot()
+ outcome['failure_observation'] = sample_failure_observation(output, flow, metro, observer)
if h.PLATFORM == 'ANDROID':
outcome['android_runtime_diagnostic'] = android_failure_observation(output, device)
if retry_fixture:
diff --git a/.github/tests/test_hosted_native.py b/.github/tests/test_hosted_native.py
index 8a73000d1..aa0472127 100644
--- a/.github/tests/test_hosted_native.py
+++ b/.github/tests/test_hosted_native.py
@@ -361,6 +361,7 @@ def compact_log(args, stdout, **kwargs):
self.assertEqual(diagnostics['parse_status'], 'PARTIAL')
self.assertEqual(diagnostics['cause'], 'UNDETERMINED')
self.assertEqual(diagnostics['category_record_counts']['JS_REFERENCE_ERROR'], 1)
+ self.assertEqual(diagnostics['query_status'], 'SUCCESS')
self.assertEqual(data['startup_diagnostics']['metro_progress'],
{'bundle_marker_observed': True, 'bundle_marker_count': 2, 'prebundle_marker_count': 1})
self.assertNotIn('private unrelated', native.EVIDENCE.read_text())
@@ -376,6 +377,7 @@ def test_ios_failed_or_timed_out_query_cannot_classify_partial_output_as_evidenc
def compact_log(args, stdout, **kwargs):
self.assertEqual(args[:4], ['xcrun', 'simctl', 'spawn', 'owned-simulator'])
self.assertIn('process == "hexa_keeper_dev"', args[-1])
+ self.assertEqual(kwargs['timeout'], 25)
stdout.write(b'2026-10-17 09:22:33.123 E hexa_keeper_dev[123:abc] TypeError: PRIVATE_SENTINEL\n')
if code == 124:
raise subprocess.TimeoutExpired(args, 25)
diff --git a/.github/tests/test_ios_startup_diagnostics.py b/.github/tests/test_ios_startup_diagnostics.py
index b1cbf7eb4..0409695d5 100644
--- a/.github/tests/test_ios_startup_diagnostics.py
+++ b/.github/tests/test_ios_startup_diagnostics.py
@@ -3,16 +3,30 @@
import json
from pathlib import Path
import unittest
+from unittest import mock
spec = importlib.util.spec_from_file_location('ios_log_controls',
Path(__file__).resolve().parents[1] / 'native/hosted_native.py')
native = importlib.util.module_from_spec(spec)
spec.loader.exec_module(native)
+ios_spec = importlib.util.spec_from_file_location('ios_pure_controls',
+ Path(__file__).resolve().parents[1] / 'native/ios_startup_errors.py')
+ios = importlib.util.module_from_spec(ios_spec)
+ios_spec.loader.exec_module(ios)
+
class IOSStartupDiagnosticsTests(unittest.TestCase):
- def record(self, message, process='hexa_keeper_dev', severity='Df'):
- return '2026-10-22 20:00:00.123+0000 %s %s[123:abc] %s' % (severity, process, message)
+ def record(self, message, process='hexa_keeper_dev', severity='Df',
+ timestamp='2026-10-22 20:00:00.123+0000', pid='123', tid='abc'):
+ return '%s %s %s[%s:%s] %s' % (timestamp, severity, process, pid, tid, message)
+
+ def assert_private_and_undetermined(self, result):
+ encoded = json.dumps(result)
+ for value in ['PRIVATE_SENTINEL', '/private/seed.js', 'https://private.invalid/',
+ 'hexa_keeper_dev']:
+ self.assertNotIn(value, encoded)
+ self.assertEqual(result['cause'], 'UNDETERMINED')
def test_known_js_native_bundle_and_network_markers_are_fixed_not_error_excerpts(self):
cases = {
@@ -71,6 +85,175 @@ def test_generic_errors_remain_unclassified_and_missing_records_remain_unknown(s
self.assertFalse(any(absent['category_record_counts'].values()))
self.assertNotIn('PRIVATE_SENTINEL', json.dumps((result, absent)))
+ def test_supported_compact_timestamps_severity_and_thread_formats_keep_positive_records(self):
+ cases = [
+ ('2026-01-15 20:41:18.941', 'Df', '11135', '3f6df'),
+ ('2026-10-22 09:22:33', 'Db', '123', 'abc'),
+ ('2026-10-22T09:22:33Z', 'I', '1', '0xabc'),
+ ('2026-10-22 09:22:33.123456+0000', 'E', '4321', '0x58ff'),
+ ('2026-10-22T09:22:33.123456789+00:00', 'F', '2147483647', 'ABCDEF0123456789'),
+ ('2026-10-22 09:22:33.1-0700', 'Df', '123', 'abc'),
+ ('2026-10-22T09:22:33-07:00', 'Df', '123', 'abc'),
+ ]
+ for timestamp, severity, pid, tid in cases:
+ with self.subTest(timestamp=timestamp, severity=severity):
+ result = native.ios_startup_diagnostics(self.record(
+ 'TypeError\tPRIVATE_SENTINEL', timestamp=timestamp,
+ severity=severity, pid=pid, tid=tid) + '\r\n', 'hexa_keeper_dev')
+ self.assertEqual(result['matching_process_records'], 1)
+ self.assertEqual(result['error_records'], 1)
+ self.assertEqual(result['category_record_counts']['JS_TYPE_ERROR'], 1)
+ self.assertEqual(result['parse_status'], 'PARSED')
+ self.assertEqual(result['malformed_record_lines'], 0)
+ self.assert_private_and_undetermined(result)
+
+ def test_invalid_record_framing_cannot_create_own_process_error_evidence(self):
+ bad_records = {
+ 'invalid month': self.record('TypeError PRIVATE_SENTINEL', timestamp='2026-99-22 09:22:33'),
+ 'invalid day': self.record('TypeError PRIVATE_SENTINEL', timestamp='2026-02-30 09:22:33'),
+ 'invalid time': self.record('TypeError PRIVATE_SENTINEL', timestamp='2026-10-22 25:22:33'),
+ 'unknown severity': self.record('TypeError PRIVATE_SENTINEL', severity='INJECTED'),
+ 'zero pid': self.record('TypeError PRIVATE_SENTINEL', pid='0'),
+ 'pid beyond signed range': self.record('TypeError PRIVATE_SENTINEL', pid='2147483648'),
+ 'oversized pid': self.record('TypeError PRIVATE_SENTINEL', pid='9999999999'),
+ 'nonhex thread': self.record('TypeError PRIVATE_SENTINEL', tid='xxx'),
+ 'nul': self.record('TypeError PRIVATE_SENTINEL\x00'),
+ 'embedded carriage return': self.record('TypeError PRIVATE_SENTINEL\rforged'),
+ 'vertical tab forged prefix': self.record('ordinary startup') + '\x0b' +
+ self.record('TypeError PRIVATE_SENTINEL'),
+ }
+ for kind, payload in bad_records.items():
+ with self.subTest(kind=kind):
+ result = native.ios_startup_diagnostics(payload, 'hexa_keeper_dev')
+ self.assertEqual(result['matching_process_records'], 0)
+ self.assertEqual(result['error_records'], 0)
+ self.assertFalse(any(result['category_record_counts'].values()))
+ self.assertEqual(result['errors'], [])
+ self.assertEqual(result['malformed_record_lines'], 1)
+ self.assertEqual(result['parse_status'], 'UNKNOWN')
+ self.assert_private_and_undetermined(result)
+
+ def test_record_byte_boundary_keeps_complete_records_and_rejects_oversized_utf8(self):
+ limit = 16 * 1024
+ self.assertEqual(ios.MAX_RECORD_BYTES, limit)
+ prefix = self.record('TypeError PRIVATE_SENTINEL ')
+ exact = prefix + 'x' * (limit - len(prefix.encode()))
+ result = native.ios_startup_diagnostics(exact + '\n', 'hexa_keeper_dev')
+ self.assertEqual(result['matching_process_records'], 1)
+ self.assertEqual(result['category_record_counts']['JS_TYPE_ERROR'], 1)
+ self.assertEqual(result['oversized_record_lines'], 0)
+ self.assertEqual(result['parse_status'], 'PARSED')
+ self.assert_private_and_undetermined(result)
+
+ multibyte = self.record('TypeError PRIVATE_SENTINEL ' + '\u79d8' * (limit // 2))
+ self.assertLess(len(multibyte), limit)
+ self.assertGreater(len(multibyte.encode()), limit)
+ for payload in [exact + 'x', multibyte]:
+ with self.subTest(multibyte=payload is multibyte):
+ result = native.ios_startup_diagnostics(
+ payload + '\n' + self.record('ordinary startup'), 'hexa_keeper_dev')
+ self.assertEqual(result['matching_process_records'], 1)
+ self.assertEqual(result['error_records'], 0)
+ self.assertEqual(result['oversized_record_lines'], 1)
+ self.assertEqual(result['parse_status'], 'PARTIAL')
+ self.assert_private_and_undetermined(result)
+
+ def test_one_mebibyte_prefix_discards_a_cut_record_even_when_its_error_marker_fits(self):
+ limit = 1024 * 1024
+ self.assertEqual(ios.MAX_INPUT_BYTES, limit)
+ first = self.record('No bundle URL present PRIVATE_SENTINEL') + '\n'
+ cut = self.record('TypeError PRIVATE_SENTINEL ')
+ padding = 'x' * (limit - len(first.encode()) - len(cut.encode()) - 9) + '\n'
+ payload = first + padding + cut + 'z' * 100
+ self.assertGreater(len(payload.encode()), limit)
+ self.assertIn('TypeError', payload[:limit])
+ result = native.ios_startup_diagnostics(payload, 'hexa_keeper_dev')
+ self.assertTrue(result['input_truncated'])
+ self.assertEqual(result['matching_process_records'], 1)
+ self.assertEqual(result['category_record_counts']['SCRIPT_URL_MISSING'], 1)
+ self.assertEqual(result['category_record_counts']['JS_TYPE_ERROR'], 0)
+ self.assertEqual(result['parse_status'], 'PARTIAL')
+ self.assert_private_and_undetermined(result)
+
+ # A multibyte cut with no complete newline contributes no partial row.
+ result = native.ios_startup_diagnostics(
+ self.record('TypeError PRIVATE_SENTINEL ' + '\u79d8' * limit), 'hexa_keeper_dev')
+ self.assertTrue(result['input_truncated'])
+ self.assertEqual(result['matching_process_records'], 0)
+ self.assertEqual(result['errors'], [])
+ self.assertEqual(result['parse_status'], 'UNKNOWN')
+ self.assert_private_and_undetermined(result)
+
+ def test_scan_and_own_record_limits_do_not_classify_unobserved_tail(self):
+ self.assertEqual(ios.MAX_SCAN_LINES, 4096)
+ self.assertEqual(ios.MAX_OWN_RECORDS, 4096)
+ with mock.patch.object(ios, 'MAX_SCAN_LINES', 2):
+ result = ios.classify('notice\n' +
+ self.record('ordinary startup') + '\n' +
+ self.record('TypeError PRIVATE_SENTINEL'), 'hexa_keeper_dev')
+ self.assertTrue(result['scan_limit_reached'])
+ self.assertEqual(result['matching_process_records'], 1)
+ self.assertEqual(result['error_records'], 0)
+ self.assertEqual(result['parse_status'], 'PARTIAL')
+ self.assert_private_and_undetermined(result)
+
+ with mock.patch.object(ios, 'MAX_OWN_RECORDS', 1):
+ result = ios.classify('\n'.join([
+ self.record('TypeError PRIVATE_SENTINEL', process='OtherApp'),
+ self.record('ordinary startup'),
+ self.record('TypeError PRIVATE_SENTINEL'),
+ ]), 'hexa_keeper_dev')
+ self.assertTrue(result['record_limit_reached'])
+ self.assertEqual(result['matching_process_records'], 1)
+ self.assertEqual(result['error_records'], 0)
+ self.assertEqual(result['parse_status'], 'PARTIAL')
+ self.assert_private_and_undetermined(result)
+
+ def test_partial_input_retains_valid_positive_counts_without_claiming_complete_parse(self):
+ result = native.ios_startup_diagnostics(
+ self.record('TypeError PRIVATE_SENTINEL \ufffd'), 'hexa_keeper_dev')
+ self.assertTrue(result['replacement_character_observed'])
+ self.assertEqual(result['matching_process_records'], 1)
+ self.assertEqual(result['category_record_counts']['JS_TYPE_ERROR'], 1)
+ self.assertEqual(result['errors'], ['IOS_STARTUP_ERROR'])
+ self.assertEqual(result['parse_status'], 'PARTIAL')
+ self.assert_private_and_undetermined(result)
+
+ result = native.ios_startup_diagnostics(self.record('ordinary startup') + '\n' +
+ self.record('TypeError PRIVATE_SENTINEL', timestamp='2026-99-22 09:22:33'),
+ 'hexa_keeper_dev')
+ self.assertEqual(result['matching_process_records'], 1)
+ self.assertEqual(result['error_records'], 0)
+ self.assertEqual(result['malformed_record_lines'], 1)
+ self.assertEqual(result['parse_status'], 'PARTIAL')
+ self.assert_private_and_undetermined(result)
+
+ def test_observed_size_2446_generic_records_remains_complete_and_unclassified(self):
+ payload = (self.record('PRIVATE_SENTINEL arbitrary application text', severity='E') + '\n') * 2446
+ result = native.ios_startup_diagnostics(payload, 'hexa_keeper_dev')
+ self.assertEqual(result['matching_process_records'], 2446)
+ self.assertEqual(result['error_records'], 2446)
+ self.assertEqual(result['unclassified_error_records'], 2446)
+ self.assertFalse(any(result['category_record_counts'].values()))
+ self.assertFalse(result['input_truncated'])
+ self.assertFalse(result['scan_limit_reached'])
+ self.assertFalse(result['record_limit_reached'])
+ self.assertEqual(result['parse_status'], 'PARSED')
+ self.assert_private_and_undetermined(result)
+
+ def test_empty_foreign_and_unframed_text_remain_unknown_without_private_output(self):
+ payloads = ['', 'PRIVATE_SENTINEL /private/seed.js https://private.invalid/',
+ self.record('TypeError PRIVATE_SENTINEL', process='OtherApp'),
+ ' ' + self.record('TypeError PRIVATE_SENTINEL'),
+ 'malformed PRIVATE_SENTINEL \ufffd']
+ for payload in payloads:
+ with self.subTest(payload_present=bool(payload)):
+ result = native.ios_startup_diagnostics(payload, 'hexa_keeper_dev')
+ self.assertEqual(result['matching_process_records'], 0)
+ self.assertEqual(result['parse_status'], 'UNKNOWN')
+ self.assertEqual(result['errors'], [])
+ self.assert_private_and_undetermined(result)
+
if __name__ == '__main__':
unittest.main()
diff --git a/.github/tests/test_product_failure_diagnosis.py b/.github/tests/test_product_failure_diagnosis.py
new file mode 100644
index 000000000..55a1e9205
--- /dev/null
+++ b/.github/tests/test_product_failure_diagnosis.py
@@ -0,0 +1,320 @@
+import contextlib
+import copy
+import hashlib
+import importlib.util
+import json
+from pathlib import Path
+import tempfile
+import types
+import unittest
+from unittest import mock
+
+NATIVE = Path(__file__).parents[1] / 'native'
+
+
+def load(name):
+ spec = importlib.util.spec_from_file_location(name, NATIVE / (name + '.py'))
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+diagnosis = load('product_failure_diagnosis')
+product = load('product_measurements')
+
+
+class FileObservations(unittest.TestCase):
+ def setUp(self):
+ self.temp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.temp.cleanup)
+ self.root = Path(self.temp.name)
+ self.flow = 'product_first_wallet.yaml'
+
+ def report(self, message, **changes):
+ from xml.sax.saxutils import escape
+ body = ('' +
+ '' + escape(message) + '')
+ for old, new in changes.items():
+ body = body.replace(old, new)
+ (self.root / 'junit.xml').write_text(body)
+ return diagnosis.junit(self.root, self.flow)
+
+ def snapshot(self, node, number=1):
+ path = self.root / 'screen-hierarchy' / ('step-%d.json' % number)
+ path.parent.mkdir(exist_ok=True)
+ path.write_text(json.dumps(node))
+ return path
+
+ def test_pinned_junit_xml_text_exact_first_line_and_known_file_only(self):
+ for message, kind in [('Assertion is false: id: view_startNewTile is visible', 'ASSERT_VISIBLE'),
+ ('Element not found: Id matching regex: btn_skip', 'ELEMENT_NOT_FOUND')]:
+ value = self.report(message + '\nPRIVATE_SENTINEL diagnostic body')
+ self.assertEqual(value['failure_kind'], kind)
+ self.assertIn(value['failed_selector'], ('start_new_tile', 'onboarding_skip'))
+ self.assertNotIn('PRIVATE_SENTINEL', json.dumps(value))
+ for message in ['PRIVATE_SENTINEL id: view_startNewTile',
+ 'Assertion is false: id: view_startNewTile is visible PRIVATE_SENTINEL',
+ 'Assertion is false: id: view_startNewTile is visible\u2028PRIVATE_SENTINEL',
+ 'Assertion is false: id: view_startNewTile is visible\u0085PRIVATE_SENTINEL',
+ 'PRIVATE_SENTINEL\nAssertion is false: id: view_startNewTile is visible',
+ 'Element not found: id: view_startNewTile']:
+ self.assertIsNone(self.report(message)['failed_selector'])
+ self.assertEqual(self.report('Assertion is false: id: view_startNewTile is visible',
+ **{'status="ERROR"': 'status="SUCCESS"'})['state'], 'UNKNOWN')
+ self.assertEqual(diagnosis.junit(self.root, 'private.yaml')['state'], 'UNKNOWN')
+ for malformed in [{'': '', '': ''},
+ {'': ''},
+ {'': '', '': ''}]:
+ result = self.report('Assertion is false: id: view_startNewTile is visible',
+ **malformed)
+ self.assertEqual(result['state'], 'UNKNOWN')
+
+ def test_missing_malformed_entity_attribute_and_wrong_file_reports_are_unknown(self):
+ path = self.root / 'junit.xml'
+ for payload in [b'', b'', b']>',
+ ']>'.encode('utf-16'),
+ b''
+ b'']:
+ path.write_bytes(payload)
+ self.assertEqual(diagnosis.junit(self.root, self.flow)['state'], 'UNKNOWN')
+ self.report('Assertion is false: id: view_startNewTile is visible')
+ self.assertEqual(diagnosis.junit(self.root, 'product_retry.yaml')['state'], 'UNKNOWN')
+ path.unlink()
+ self.assertEqual(diagnosis.junit(self.root, self.flow)['state'], 'UNKNOWN')
+ path.symlink_to(self.root / 'outside.xml')
+ self.assertEqual(diagnosis.junit(self.root, self.flow)['state'], 'UNKNOWN')
+
+ def test_fixed_public_flags_leaf_omissions_and_no_arbitrary_values_escape(self):
+ self.snapshot({'children': [
+ {'attributes': {'resource-id': 'view_startNewTile', 'text': 'PRIVATE_SENTINEL'}},
+ {'attributes': {'resource-id': 'io.hexawallet.keeper.development:id/btn_skip'}},
+ *[{'attributes': {'text': value}} for value in [
+ 'Start New', 'Welcome to Bitcoin Keeper', 'Dismiss', 'Minimize', 'Render Error',
+ 'Unable to check your passcode. Please try again.', 'Retry',
+ '“PRIVATE_SENTINEL” Would Like to Send You Notifications', 'Allow', "Don't Allow"]]]})
+ result = diagnosis.hierarchy(self.root)
+ self.assertEqual(result['state'], 'COMPLETE')
+ for name in ('start_new_tile', 'onboarding_skip', 'start_new_text', 'welcome',
+ 'credential_error', 'retry', 'logbox_controls', 'logbox_error_header',
+ 'notification_permission_controls'):
+ self.assertIs(result['flags'][name], True, name)
+ self.assertIs(result['flags']['recover_tile'], False)
+ self.assertNotIn('PRIVATE_SENTINEL', json.dumps(result))
+
+ def test_invalid_truncated_and_bounded_snapshots_do_not_clear_unknown_flags(self):
+ self.assertTrue(all(value is None for value in diagnosis.hierarchy(self.root)['flags'].values()))
+ self.snapshot({'attributes': {'resource-id': 'btn_skip'}})
+ malformed = self.snapshot({'children': [42]}, 2)
+ result = diagnosis.hierarchy(self.root)
+ self.assertEqual(result['state'], 'PARTIAL')
+ self.assertIs(result['flags']['onboarding_skip'], True)
+ self.assertIsNone(result['flags']['start_new_tile'])
+ malformed.write_bytes(b' ' * (diagnosis.FILE_LIMIT + 1))
+ self.assertEqual(diagnosis.hierarchy(self.root)['rejected_snapshots'], 1)
+ with mock.patch.object(diagnosis, 'NODE_LIMIT', 1):
+ self.snapshot({'children': [{}]}, 1)
+ self.assertEqual(diagnosis.hierarchy(self.root)['rejected_snapshots'], 2)
+ for number in range(3, 11):
+ self.snapshot({}, number)
+ self.assertTrue(diagnosis.hierarchy(self.root)['snapshot_limit_exceeded'])
+
+ def test_isolated_permission_buttons_and_cross_snapshot_logbox_are_not_dialog_proof(self):
+ self.snapshot({'attributes': {'text': 'Allow'}, 'children': [{'attributes': {'text': 'Dismiss'}}]})
+ self.snapshot({'attributes': {'text': "Don't Allow"}, 'children': [{'attributes': {'text': 'Minimize'}}]}, 2)
+ result = diagnosis.hierarchy(self.root)
+ self.assertIs(result['flags']['notification_permission_controls'], False)
+ self.assertIs(result['flags']['logbox_controls'], False)
+
+ def test_duplicate_falsey_malformed_and_symlink_inputs_stay_unknown(self):
+ path = self.snapshot({})
+ for payload in [b'{"attributes":{},"attributes":{"text":"PRIVATE_SENTINEL"}}',
+ b'{"attributes":null}', b'{"attributes":false}', b'{"attributes":[]}',
+ b'{"children":null}', b'{"children":false}', b'{"children":{}}',
+ b'{"attributes":{"text":42}}']:
+ with self.subTest(payload=payload):
+ path.write_bytes(payload)
+ value = diagnosis.hierarchy(self.root)
+ self.assertEqual(value['state'], 'UNKNOWN')
+ self.assertTrue(all(flag is None for flag in value['flags'].values()))
+ self.assertNotIn('PRIVATE_SENTINEL', json.dumps(value))
+ path.unlink()
+ outside = self.root / 'outside.json'
+ outside.write_text('{}')
+ path.symlink_to(outside)
+ self.assertEqual(diagnosis.hierarchy(self.root)['state'], 'UNKNOWN')
+
+
+class MetroObservations(unittest.TestCase):
+ def setUp(self):
+ self.temp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.temp.cleanup)
+ self.root = Path(self.temp.name)
+ self.path = self.root / 'metro-01.log'
+ self.path.write_text('ERROR TypeError: PRIVATE_EARLIER\n')
+ self.process = types.SimpleNamespace(poll=lambda: None)
+ self.metro = types.SimpleNamespace(private=self.root, process=self.process,
+ phase='product', events=[{'phase': 'product'}], owned=[self.process])
+
+ def append(self, value):
+ with self.path.open('ab') as output:
+ output.write(value)
+
+ def test_only_bound_sample_lines_and_fixed_categories_are_retained_even_after_exit(self):
+ bound = diagnosis.bind_metro(self.metro)
+ self.append(b'ERROR ReferenceError: PRIVATE_SENTINEL https://example.test/?secret=value\n')
+ self.process.poll = lambda: -9
+ value = diagnosis.metro_window(self.metro, bound)
+ self.assertEqual(value['state'], 'COMPLETE')
+ self.assertEqual(value['fault_categories'], ['JS_REFERENCE_ERROR'])
+ self.assertEqual((value['process_state'], value['exit_code']), ('EXITED', -9))
+ self.assertEqual(value['error_headers'], 1)
+ for forbidden in ('PRIVATE', 'example.test', 'secret', 'TYPE_ERROR'):
+ self.assertNotIn(forbidden, json.dumps(value))
+
+ def test_missing_replaced_shrunk_or_other_process_phase_event_cannot_be_adopted(self):
+ for change in ('missing', 'replaced', 'shrunk', 'process', 'phase', 'event', 'unowned'):
+ with self.subTest(change=change):
+ self.setUp()
+ bound = diagnosis.bind_metro(self.metro)
+ if change == 'missing':
+ self.path.unlink()
+ elif change == 'replaced':
+ replacement = self.root / 'replacement'
+ replacement.write_text('ERROR TypeError: PRIVATE_SENTINEL\n')
+ replacement.replace(self.path)
+ elif change == 'shrunk':
+ self.path.write_bytes(b'')
+ elif change == 'process':
+ self.metro.process = types.SimpleNamespace(poll=lambda: None)
+ elif change == 'phase':
+ self.metro.phase = 'arm'
+ elif change == 'event':
+ self.metro.events.append({'phase': 'product'})
+ else:
+ self.metro.owned = []
+ self.assertEqual(diagnosis.metro_window(self.metro, bound)['state'], 'UNKNOWN')
+
+ def test_partial_start_end_limit_and_growth_are_disclosed(self):
+ self.path.write_bytes(b'PRIVATE_EARLIER_PARTIAL')
+ bound = diagnosis.bind_metro(self.metro)
+ self.append(b' TypeError\nERROR ReferenceError: PRIVATE_SENTINEL\nERROR SyntaxError: unfinished')
+ result = diagnosis.metro_window(self.metro, bound)
+ self.assertEqual(result['state'], 'PARTIAL')
+ self.assertTrue(result['partial_start'])
+ self.assertTrue(result['partial_end'])
+ self.assertEqual(result['fault_categories'], ['JS_REFERENCE_ERROR'])
+ with mock.patch.object(diagnosis, 'METRO_LIMIT', 18):
+ result = diagnosis.metro_window(self.metro, bound)
+ self.assertTrue(result['input_truncated'])
+ self.assertLessEqual(result['bytes_read'], 18)
+ original = diagnosis.os.fstat
+ calls = []
+ def growing(fd):
+ info = original(fd)
+ calls.append(fd)
+ if len(calls) == 2:
+ return types.SimpleNamespace(st_size=info.st_size + 1)
+ return info
+ with mock.patch.object(diagnosis.os, 'fstat', side_effect=growing):
+ result = diagnosis.metro_window(self.metro, bound)
+ self.assertTrue(result['growth_detected'])
+ self.assertEqual(result['state'], 'PARTIAL')
+
+ def test_malformed_utf8_controls_and_non_lf_separators_cannot_create_error_facts(self):
+ bound = diagnosis.bind_metro(self.metro)
+ for payload in [b'INFO not a newline\rERROR TypeError: PRIVATE_SENTINEL\n',
+ b'ERROR TypeError: \xff PRIVATE_SENTINEL\n',
+ b'ERROR TypeError: PRIVATE_SENTINEL\x00\n',
+ 'INFO\u2028ERROR TypeError: PRIVATE_SENTINEL\n'.encode()]:
+ with self.subTest(payload=payload):
+ self.path.write_bytes(self.path.read_bytes()[:bound.offset] + payload)
+ result = diagnosis.metro_window(self.metro, bound)
+ self.assertEqual(result['state'], 'UNKNOWN')
+ self.assertEqual(result['fault_categories'], [])
+ self.assertEqual(result['invalid_records'], 1)
+ self.assertEqual(result['error_headers'], 0)
+ self.assertNotIn('PRIVATE_SENTINEL', json.dumps(result))
+ self.path.write_bytes(self.path.read_bytes()[:bound.offset] +
+ b'ERROR TypeError: PRIVATE_SENTINEL\x00\n\x1b[31mERROR ReferenceError: fixed\x1b[0m\r\n')
+ result = diagnosis.metro_window(self.metro, bound)
+ self.assertEqual(result['state'], 'PARTIAL')
+ self.assertEqual((result['valid_records'], result['invalid_records']), (1, 1))
+ self.assertEqual(result['fault_categories'], ['JS_REFERENCE_ERROR'])
+
+
+class FailureLifecycle(unittest.TestCase):
+ def test_original_error_identity_and_purge_survive_failed_observer_and_cleanup(self):
+ class PrimaryFailure(RuntimeError):
+ pass
+ with tempfile.TemporaryDirectory() as directory:
+ root, order, receipts = Path(directory), [], []
+ private = root / 'private'
+ private.mkdir()
+ (root / 'release').mkdir()
+ manifest = b'{"name":"owned"}'
+ (root / 'package.json').write_bytes(manifest)
+ (root / 'release/version.json').write_text(json.dumps(
+ {'version': '2.6.4', 'androidVersionCode': 627, 'iosBuildNumber': 620}))
+ (root / '.env.ci').write_text('\n'.join([
+ 'ENVIRONMENT=DEVELOPMENT', 'RELAY=http://127.0.0.1:8765/',
+ 'SIGNING_SERVER_TESTNET=https://127.0.0.1:9/', 'SIGNING_SERVER_MAINNET=https://127.0.0.1:9/',
+ 'CHANNEL_URL=https://127.0.0.1:9/', 'SENTRY_DNS=https://public@127.0.0.1:9/1',
+ 'ENC_KEY_STORAGE_IDENTIFIER=KEEPER-HOSTED-DISPOSABLE']))
+ sha, artifact = 'a' * 40, {'sha256': 'b' * 64}
+ digest = hashlib.sha256(manifest).hexdigest()
+ state = {'build': 'PASS', 'source_sha': sha, 'built_artifact': artifact,
+ 'commands': [], 'maestro': {'binary': 'fake-maestro'}, 'nodeify_overlay': {
+ 'path': 'package.json', 'allowed_fields': ['browser', 'react-native', 'browserify'],
+ 'before_sha256': digest, 'after_sha256': digest}}
+ error = PrimaryFailure('PRIVATE_SENTINEL original')
+ def save(value):
+ receipts.append(copy.deepcopy(value['product_ui']))
+ state.update(copy.deepcopy(value))
+ def command(args, *_args, **_kwargs):
+ state['commands'].append({})
+ if args == ['adb', 'get-serialno']:
+ return 'emulator-5554'
+ if args[0] == 'fake-maestro':
+ output = Path(args[args.index('--debug-output') + 1])
+ (output / 'junit.xml').write_text('PRIVATE_SENTINEL')
+ raise error
+ return 'image'
+ def observe(output, *_args):
+ self.assertTrue((output / 'junit.xml').exists())
+ order.append('observer')
+ raise OSError('PRIVATE_SENTINEL observation')
+ observer = types.SimpleNamespace(bind_metro=lambda _: None, collect=observe)
+ def close():
+ order.append('close')
+ raise OSError('PRIVATE_SENTINEL cleanup')
+ manager = types.SimpleNamespace(start=lambda *_a, **_k: None, close=close, events=[])
+ server = types.SimpleNamespace(serve_forever=lambda: None, shutdown=lambda: None, server_close=lambda: None)
+ def installed(_device):
+ proof = {'method': 'SINGLE_INSTALLED_BASE_APK_SHA256', 'sha256': 'c' * 64}
+ state.update(installed_artifact_verified=True, installed_artifact=proof)
+ return proof
+ h = types.SimpleNamespace(ROOT=root, PRIVATE=private, PLATFORM='ANDROID', APP_IDS={'ANDROID': 'owned.app'},
+ read=lambda: copy.deepcopy(state), save=save, artifact_identity=lambda: artifact, command=command,
+ verify_installed_artifact=installed)
+ def module(name):
+ return observer if name == 'product_failure_diagnosis' else types.SimpleNamespace(OwnedMetro=lambda *_: manager)
+ with contextlib.ExitStack() as stack:
+ stack.enter_context(mock.patch.dict(product.os.environ, {'GITHUB_ACTIONS': 'true',
+ 'RUNNER_ENVIRONMENT': 'github-hosted', 'KEEPER_SOURCE_SHA': sha}))
+ stack.enter_context(mock.patch.object(product.subprocess, 'check_output', side_effect=[sha, manifest]))
+ stack.enter_context(mock.patch.object(product.subprocess, 'run', return_value=types.SimpleNamespace(returncode=0)))
+ stack.enter_context(mock.patch.object(product, 'native_module', side_effect=module))
+ stack.enter_context(mock.patch.object(product, 'make_server', return_value=server))
+ stack.enter_context(mock.patch.object(product, 'android_failure_observation', return_value={'status': 'UNAVAILABLE'}))
+ with self.assertRaises(PrimaryFailure) as failure:
+ product.run(h)
+ self.assertIs(failure.exception, error)
+ self.assertEqual(order, ['observer', 'close'])
+ self.assertEqual(list(private.iterdir()), [])
+ self.assertEqual(len(state['product_ui']['samples']), 1)
+ self.assertEqual(state['product_ui']['samples'][0]['failure_observation']['status'], 'UNKNOWN')
+ self.assertNotIn('PRIVATE_SENTINEL', json.dumps(receipts))
+
+
+if __name__ == '__main__':
+ unittest.main()
diff --git a/.github/tests/test_startup_diagnosis.py b/.github/tests/test_startup_diagnosis.py
index e5238aaa0..f395bcf6a 100644
--- a/.github/tests/test_startup_diagnosis.py
+++ b/.github/tests/test_startup_diagnosis.py
@@ -338,6 +338,53 @@ def test_ios_supplied_falsey_nonobject_attributes_and_nonlist_children_stay_unkn
self.assertIsNone(facts['hierarchy']['credential_error'])
self.assertIn('hierarchy', facts['collection_errors'])
+ def test_ios_future_rows_are_unknown_and_build_options_remain_fixed_without_inheritance(self):
+ native = SimpleNamespace(PRIVATE=self.root, PLATFORM='IOS')
+ device = '12345678-1234-1234-1234-123456789ABC'
+ rows = [
+ {'time_ms': 149, 'kind': 'BUILD', 'event': 'bundle_build_started',
+ 'platform': 'ios', 'dev': True, 'minify': False},
+ {'time_ms': 150, 'kind': 'BUILD', 'event': 'bundle_build_done'},
+ {'time_ms': 200, 'kind': 'BUILD', 'event': 'bundle_build_failed',
+ 'platform': 'PRIVATE_SENTINEL', 'dev': 1, 'minify': 'PRIVATE_SENTINEL'},
+ {'time_ms': 201, 'kind': 'REQUEST', 'request': 'ENTRY_BUNDLE', 'options': {'platform': 'ios'}},
+ ]
+ (self.root / 'startup-observer.jsonl').write_text('\n'.join(json.dumps(row) for row in rows))
+ with mock.patch.object(diagnosis.time, 'time', return_value=0.200):
+ facts = diagnosis.collect(native, device, SimpleNamespace(started_ms=150))['metro']
+ self.assertEqual([row['stage'] for row in facts['rows']], ['BEFORE_APP', 'APP_WINDOW', 'APP_WINDOW', 'UNKNOWN'])
+ self.assertEqual({key: facts['rows'][0][key] for key in ['platform', 'dev', 'minify']},
+ {'platform': 'ios', 'dev': True, 'minify': False})
+ self.assertEqual({key: facts['rows'][1][key] for key in ['platform', 'dev', 'minify']},
+ {'platform': None, 'dev': None, 'minify': None})
+ self.assertEqual({key: facts['rows'][2][key] for key in ['platform', 'dev', 'minify']},
+ {'platform': 'OTHER', 'dev': None, 'minify': None})
+ self.assertNotIn('PRIVATE_SENTINEL', json.dumps(facts))
+
+ def test_ios_row_and_options_shapes_are_invalid_and_android_retains_canonical_fields(self):
+ native = SimpleNamespace(PRIVATE=self.root, PLATFORM='IOS')
+ device = '12345678-1234-1234-1234-123456789ABC'
+ rows = [[], None, 'PRIVATE_SENTINEL',
+ {'time_ms': 150, 'kind': 'REQUEST', 'request': 'ENTRY_BUNDLE', 'options': []},
+ {'time_ms': 150, 'kind': 'REQUEST', 'request': 'ENTRY_BUNDLE', 'options': 'PRIVATE_SENTINEL'}]
+ path = self.root / 'startup-observer.jsonl'
+ path.write_text('\n'.join(json.dumps(row) for row in rows))
+ facts = diagnosis.collect(native, device)['metro']
+ self.assertEqual(facts['invalid_rows'], len(rows))
+ self.assertEqual(facts['rows'], [])
+ self.assertEqual(facts['coverage'], 'UNKNOWN')
+ self.assertNotIn('PRIVATE_SENTINEL', json.dumps(facts))
+ path.write_text(json.dumps({'time_ms': 201, 'kind': 'BUILD', 'event': 'bundle_build_started',
+ 'platform': 'android', 'dev': True, 'minify': False}))
+ with mock.patch.object(diagnosis.time, 'time', return_value=0.200), \
+ mock.patch.object(diagnosis.subprocess, 'run', return_value=SimpleNamespace(returncode=1, stdout=b'')):
+ facts = diagnosis.collect(self.native, 'emulator-5554', SimpleNamespace(started_ms=150))['metro']
+ self.assertEqual(facts['rows'][0]['stage'], 'UNKNOWN', 'retain the reviewed canonical future bound')
+ self.assertEqual(facts['rows'][0]['platform'], 'android')
+ self.assertIs(facts['rows'][0]['dev'], True)
+ self.assertIs(facts['rows'][0]['minify'], False)
+ self.assertNotIn('coverage', facts)
+
if __name__ == '__main__':
diff --git a/docs/product-failure-observation.md b/docs/product-failure-observation.md
new file mode 100644
index 000000000..62a00e706
--- /dev/null
+++ b/docs/product-failure-observation.md
@@ -0,0 +1,97 @@
+# Failed product sample observation
+
+Stage B merges completed #7116 checkpoint
+`1bc34890cb8618b2fffd446a63924974e0fe15b5` into the separately frozen Stage A
+`ba8c6958b214920a56c06ee78db8c87a40ebf237` by ancestry.
+[Producer patch](https://github.com/KeeperCommunity/bitcoin-keeper/compare/76d1c949d91c5d885fc002f689a9ec321c16eafb...1bc34890cb8618b2fffd446a63924974e0fe15b5)
+and [original draft #7116](https://github.com/KeeperCommunity/bitcoin-keeper/pull/7116)
+retain their original source/check attribution. Stage A's single pure compact-log
+classifier, canonical fixed fields and cleanup remain unchanged.
+
+This preparation adds observation only. It changes no application code,
+dependencies, Maestro flow, selector, deadline, Metro configuration or lifecycle,
+and adds no native query, capture process, retry or validation window.
+
+Run `39846002094`, attempt `1`, source
+`23f14e01f3437c213f1443c3167d96022f3a43bc` completed naturally. Android build,
+startup smoke, persistence probe, five production-worker scenarios, exact source
+receipts and installed APK bytes passed. Full-product sample 1 failed after the
+host acknowledged the Skip command, before `start_new_visible`. That optional
+marker prefix alone does not identify the failed Maestro command or an app
+defect. Samples 2–5, full-product Retry/key-PIN checks and physical checks did not
+run. The new reader has not run on a native host, and cannot add evidence to that
+older source. Its cause remains undetermined.
+
+Artifact 12458149136 has API/upload/download ZIP SHA256
+`4d464ef5f8faa7de4f02292e683f0dad8242544843610da9371f2c675dc183f0`.
+The only raw full-product duration was startup-to-passcode 21652.183ms; worker
+helper timings do not satisfy the five full-product samples. Installed APK bytes
+passed before and after the completed probes and before the failed product
+sample; its post-product comparison did not run.
+
+The product coordinator calls `product_failure_diagnosis.py` on failure, before
+removing that sample's private output. Observer/import failures yield UNKNOWN
+and retain the original exception. Existing sample and outer cleanup still run;
+raw JUnit, hierarchy, screenshots, app output and Metro logs remain private and
+are removed by the existing cleanup. The Android post-failure four-command
+collector is unchanged and retains its separate unknown-freshness scope.
+
+The reader exports three separate observations:
+
+- JUnit: only the pinned Maestro 2.11 XML-text failure format from the expected
+ single flow/test case, with status ERROR. A complete first line must equal a
+ fixed known assertion/element selector message. Other messages disclose only
+ ERROR_RECORDED or UNKNOWN. Failure attributes, custom labels, suffix matches,
+ unknown flow files, multiple failures and malformed XML cannot identify a
+ selector. No missing PIN marker is converted into a failed command.
+- Hierarchy: fixed public IDs and strings for Skip, Start New, recovery/settings,
+ welcome/passcode/credential Retry, LogBox and notification permission controls.
+ This is explicitly ANY_RETAINED_SNAPSHOT, never the final post-Skip screen or
+ proof of current visibility, route, app ownership or tap delivery. Paired
+ LogBox/notification controls must occur within one snapshot. Allow/Don't Allow
+ alone does not establish a permission dialog. Modern LogBox resource IDs are
+ not treated as reliable iOS accessibility IDs.
+- Product Metro: immediately before the original Maestro command, bind the
+ original owned Popen object, product phase, event count, regular log file
+ device/inode and EOF offset. On failure, require the same ownership, phase,
+ event and file identity; inspect only newly appended complete lines. Earlier
+ warmup and sample bytes are excluded. An exited owned Metro can still supply
+ its bound log; its numeric exit status is an observation, not cause proof.
+
+JUnit/hierarchy reads are limited to 1 MiB per file, eight snapshots, 10,000 nodes
+per snapshot and depth 128. Oversized, duplicate-key, malformed, invalid-shape or
+symlink inputs cannot establish absent UI. Partial coverage keeps unseen flags
+null; true flags describe positive observations in a valid retained snapshot.
+False flags describe only complete scanned snapshots. No arbitrary hierarchy
+attribute, error text, URL, query string, filename or device text is exported.
+
+Metro reads at most the latest 256 KiB appended within the bound window, trims
+partial starting/ending lines, and discloses byte counts, truncation, partial
+boundaries and growth during reading. Missing, replaced, shrunk or differently
+owned logs remain UNKNOWN. Records use LF boundaries, optional CRLF endings and
+strict UTF-8; unsupported controls or invalid encoding increase fixed rejected
+record counts and cannot establish an error category. Fixed console error categories do not establish
+request success, bundle completion, runtime readiness, app health or root cause.
+
+Format evidence is in pinned Maestro `cli-2.11.0` sources, commit
+`c8c361be1cc89b2e742f185466a302a22778be6b`:
+`JUnitTestSuiteReporter.kt` writes `Failure.message` as XML text;
+`TestSuiteInteractor.kt` uses the flow exception message;
+`Orchestra.kt`, `Condition.kt` and `ElementSelector.kt` define the exact assertion
+and element-selector descriptions. `ArtifactsGenerator.kt` serializes the root
+`TreeNode`; the writer omits empty fields. App IDs/public text are defined by
+`OnBoardingSlides.tsx`, `NewKeeperAppScreen.tsx` and English localization.
+React Native 0.83.9 LogBox sources define its public footer/header strings;
+Maestro's `PermissionButtonFinder.swift` supplies the notification prompt phrase.
+
+Host tests cover exact/negative formats, privacy sentinels, malformed/falsey and
+duplicate fields, bounded/partial coverage, Metro source/window binding, and
+preservation of the original failure plus purge when observation and cleanup
+throw. The producer recorded152 Node/246 Python offline controls on its source.
+Those counts are preserved at that producer; they are not passes for this
+combined Stage B. Fresh exact-commit combined Node/Python, privacy/lifecycle
+and workflow checks are recorded in its separate handoff before publication.
+These controls provide no native acceptance and select no additional window.
+The producer's existing native work is preserved and must finish naturally;
+its results remain scoped to that producer SHA. No producer ref/label/job is
+changed by this reconciliation.
diff --git a/docs/r5-ios-startup-observation.md b/docs/r5-ios-startup-observation.md
index 6b86d510b..9bd5c4e83 100644
--- a/docs/r5-ios-startup-observation.md
+++ b/docs/r5-ios-startup-observation.md
@@ -7,8 +7,9 @@ source `eceb5551a430a0e31cff7a32d70181ee55007b69` already included in
checkpoint `76d1c949d91c5d885fc002f689a9ec321c16eafb` by ancestry.
[Original #7115 patch](https://github.com/KeeperCommunity/bitcoin-keeper/compare/c8c4e22ffc0137f774e533f167ada81aa673b94a...eceb5551a430a0e31cff7a32d70181ee55007b69)
and [original #7116 startup patch](https://github.com/KeeperCommunity/bitcoin-keeper/compare/23f14e01...76d1c949d91c5d885fc002f689a9ec321c16eafb)
-retain their producing sources and receipts. Later product-failure observation
-at `1bc34890cb8618b2fffd446a63924974e0fe15b5` is a separate Stage B package.
+retain their producing sources and receipts. Stage B preserves the frozen Stage A source and merges product-failure
+observation at `1bc34890cb8618b2fffd446a63924974e0fe15b5` by ancestry; see
+[its separate observation contract](product-failure-observation.md).
No original producer or main integration branch is rewritten.
## Compact-log receipt