feat(01-06): collect bounded Linux capture and honest failed preflight

This commit is contained in:
UnixNight committed 2026-11-13 11:56:08 -05:00
1 parent 9c59f60b50
commit 16f5e126be
3 files changed
+439

No files matched your search

+85
View File
@@ -0,0 +1,85 @@
# Local Linux fidelity capture
This joins the single final combined session described in
[windows-session.md](windows-session.md). Prepare locally; no early hands-on
session is requested. Every original/native acceptance obligation remains open
until actual evidence and human review. No gameplay/movement reset is added.
Use the existing sealed Linux package, not a rebuilt or relabeled package.
The 01-05 package is `artifacts/fidelity/01-05-packages/linux-x64`:
source `446930d2a30d6d616c60ac5e59e4169a840bea09`, dirty yes, publish diff
`90cef95669caece53fe2d2c4736cf2ac05ed27f5d25ca03ab572589686bcb73d`.
Its file-list hash is `124cf271e4952f3822eec5c24358447fcffc9e9e1803aded8d96d4d4472dc5a3`.
The collector checks all sealed bytes before launch and collection. Keep output
outside the package and originals, in a fresh session directory.
Select the actual local X11 display and capture rectangle, real Pulse monitor
source and physical input method. Save a local JSON settings object with these
exact fields (values below are examples, not observed devices):
```json
{"display_method":"x11","display":":0","audio_method":"pulse",
"audio_source":"actual-device.monitor","input_method":"physical",
"size":"1280x720","offset":"0,0"}
```
Inspect `pactl list short sources` and `pactl list short sinks` locally. Null/dummy
devices do not qualify. This collector implements X11/Pulse capture with installed
FFmpeg/ffprobe; it records unsupported Wayland/TTY/dependency conditions as failed
preflight. Do not install or select a guessed alternative automatically. Use a
separately identified existing recorder for unsupported display sources and retain
its actual settings, tool identity, raw recording and timing provenance.
```sh
bash scripts/collect-fidelity-linux.sh preflight --package artifacts/fidelity/01-05-packages/linux-x64 --settings /local/linux-settings.json
bash scripts/collect-fidelity-linux.sh run --package artifacts/fidelity/01-05-packages/linux-x64 --settings /local/linux-settings.json --output artifacts/fidelity/linux/unique-launch --session-id unique-launch --case-id fresh-natural-ordinary --scope dialogue-return --seconds 120
bash scripts/collect-fidelity-linux.sh collect --run artifacts/fidelity/linux/unique-launch --import-to artifacts/fidelity/linux-receipts
```
Nonzero run/collect exits preserve failure/abort output; inspect it, and collect
the failed run too. Recorder starts before the normal `--load-save NewGame.tsk
--walk` process and passive observer. This is the existing story entry, not an
implemented main menu. Close the game normally before the selected duration.
Both children have one bounded deadline; interruption ends only owned children.
Logs and metadata have explicit bounds; raw recording is capped at 8 GiB. Retain
the entire lossless FFV1/PCM MKV and tail; a detected frozen interval is an open
inspection flag, not a claim of failure or parity derived from a numeric tolerance.
Collection probes actual streams/duration and hashes logs/media/observer and
package/source/resource identities. The duplicate MKV audio alias preserves exact
bytes for the shared receipt's distinct audio role. No audio normalization,
retiming, crop repair or preview is implicit. If a browser needs a remux/preview,
retain raw media and explicit derivation command/version/hash/time mapping under
the existing shared derivative contract. The local viewer exporter consumes the
imported receipts; actual playback/seeking/audio/crop remain human review gates.
Record manual event annotations as `{"events":[...]}` using the exact fields in
`scenarios.json`: hashed raw artifact name, media and monotonic elapsed seconds,
method and uncertainty. Supply `collect --annotations /local/annotations.json`.
Port simulation ticks remain separate from raw clocks. Observer gate results
do not prove a physical key was pressed. Automated injection is `port_fixture`;
test doubles are permanently synthetic. No collector output grants acceptance.
## Actual 2026-11-13 preflight
The scoped host probe, outside sandbox device restrictions, found a TTY session,
no `DISPLAY` or `WAYLAND_DISPLAY` and no X11 socket. Existing FFmpeg/ffprobe are
available. Pulse exposes only `auto_null` and `auto_null.monitor` (suspended).
No Xvfb or OBS command resolved. A synthetic display or null audio would not
establish the requested normal visible/audible gameplay, so no game/recorder
was launched and no substitute route/media was fabricated.
The exact failed focused receipt is `linux-01-06-focused-preflight-linux`, at
`artifacts/fidelity/linux/01-06-focused-preflight/receipt.json`, imported into
`artifacts/fidelity/linux-receipts/linux-01-06-focused-preflight-linux/`.
`preflight.json` preserves observed OS, tool versions/hashes, Pulse devices and
available GPU/Vulkan diagnostics; missing SDL/active-instance runtime versions
remain explicit. The selected package/resource seal matches the hash above.
Both the failed result and its import validate structurally, with acceptance open.
Before collection, all 539 original files verified unchanged.
Required next physical session: provide an actual display/game capture source
and real audible device/monitor source, verify moving unobstructed content and
audio, then record physical normal controls and full tails. Inspect capture cost,
crop/aspect and actual browser playback/seeking separately. Preserve this failed
preflight as history; new attempts use new session IDs and fresh output roots.
+5
View File
@@ -0,0 +1,5 @@
#!/usr/bin/env bash
# No build, download, device fallback or acceptance promotion.
set -euo pipefail
task_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
exec python3 "$task_root/tools/recon/fidelity_capture.py" "$@"
+349
View File
@@ -0,0 +1,349 @@
#!/usr/bin/env python3
"""Local Linux capture. Collection never grants physical/audible acceptance.
Only tool-owned argument arrays execute. Immutable package bytes are checked at
both boundaries; output is fresh and disjoint. No original is executed or copied.
X11/Pulse are the implemented external recorder sources; unsupported sources
produce precise failed receipts rather than dummy fallback recordings.
"""
import argparse
import json
import math
import os
from pathlib import Path
import platform
import re
import shutil
import signal
import subprocess
import tempfile
import time
from fidelity_checkpoint import _package
from fidelity_receipts import (MAX_JSON_BYTES, _id, _write_json, canonical_bytes,
contained_path, identify_file, import_receipt, read_json, separated_roots,
utc_now, validate_receipt, validate_scenario_contract)
PROJECT = Path(__file__).resolve().parents[2]
MAX_SECONDS = 3600
MAX_LOG = 32 * 1024**2
MAX_MEDIA = 8 * 1024**3
def command_probe(argv, timeout=10):
"""Bound subprocess lifetime and returned metadata; no unbounded PIPE buffer."""
try:
with tempfile.TemporaryFile() as log:
process = subprocess.Popen(argv, stdout=log, stderr=log, start_new_session=True)
try:
code = process.wait(timeout=timeout)
except subprocess.TimeoutExpired:
os.killpg(process.pid, signal.SIGKILL)
process.wait(timeout=5)
code = None
log.seek(0)
data = log.read(MAX_JSON_BYTES + 1)
error = 'metadata timeout' if code is None else None
if len(data) > MAX_JSON_BYTES:
error = 'metadata exceeds 4 MiB'; data = data[:MAX_JSON_BYTES]
return {'argv': argv, 'exit_code': code, 'stdout': data.decode('utf8', errors='replace'), 'error': error}
except OSError as error:
return {'argv': argv, 'exit_code': None, 'stdout': '', 'error': str(error)}
def _settings(settings):
expected = {'display_method', 'display', 'audio_method', 'audio_source',
'input_method', 'size', 'offset'}
if set(settings) != expected or any(not isinstance(v, str) or len(v) > 256 for v in settings.values()):
raise ValueError('Settings require exactly the documented bounded string fields')
if settings['input_method'] not in ('physical', 'automated', 'headless'):
raise ValueError('Unknown input method')
if not re.fullmatch(r'[1-9][0-9]{1,3}x[1-9][0-9]{1,3}', settings['size']):
raise ValueError('Explicit bounded capture size required')
if not re.fullmatch(r'[0-9]{1,5},[0-9]{1,5}', settings['offset']):
raise ValueError('Explicit nonnegative X11 offset required')
if settings['display'] and not re.fullmatch(r':[0-9]{1,5}(?:\.[0-9]{1,2})?', settings['display']):
raise ValueError('Only local X11 displays are supported')
if settings['audio_source'] and not re.fullmatch(r'[A-Za-z0-9_.-]{1,200}', settings['audio_source']):
raise ValueError('Explicit local Pulse source name required')
return dict(settings)
def preflight(package, settings, tooling=False, probe=command_probe):
settings = _settings(settings)
blockers, observations = [], {}
package = Path(package).resolve(strict=True)
identity = None
try:
identity = _package(package, 'linux-x64', tooling)
if not os.access(package / 'GamePort', os.X_OK):
blockers.append('Identified Linux apphost is not executable')
except (ValueError, OSError) as error:
blockers.append('Package identity: ' + str(error))
if platform.system() != 'Linux': blockers.append('Native Linux host required')
for name, argv in {'recorder': ['ffmpeg', '-version'], 'media_probe': ['ffprobe', '-version'],
'pulse_sources': ['pactl', 'list', 'short', 'sources'],
'pulse_sinks': ['pactl', 'list', 'short', 'sinks'],
'gpu': ['lspci', '-nn'], 'vulkan': ['vulkaninfo', '--summary']}.items():
observations[name] = probe(argv, timeout=10)
executable = shutil.which(argv[0])
if executable:
observations[name]['executable'] = {'path': str(Path(executable).resolve()),
**identify_file(Path(executable).resolve())}
for name in ('recorder', 'media_probe'):
if observations[name]['exit_code'] != 0 or observations[name]['error']:
blockers.append('Unavailable local ' + name)
if settings['display_method'] != 'x11' or not settings['display']:
blockers.append('No selected usable X11 display; Wayland/TTY capture requires a separately verified recorder')
else:
result = probe(['ffmpeg', '-nostdin', '-hide_banner', '-f', 'x11grab',
'-video_size', settings['size'], '-i', settings['display'] + '+' + settings['offset'],
'-frames:v', '1', '-f', 'null', '-'], timeout=10)
observations['display_probe'] = result
if result['exit_code'] != 0 or result['error']: blockers.append('Selected display capture probe failed')
source = settings['audio_source']
if settings['audio_method'] != 'pulse' or not source or any(x in source.lower() for x in ('null', 'dummy')):
blockers.append('No selected real Pulse audio source; null/dummy output cannot prove audible gameplay')
elif observations['pulse_sources']['exit_code'] != 0 or source not in [
line.split()[1] for line in observations['pulse_sources']['stdout'].splitlines() if len(line.split()) >= 2]:
blockers.append('Selected Pulse source is unavailable')
else:
result = probe(['ffmpeg', '-nostdin', '-hide_banner', '-f', 'pulse', '-i', source,
'-t', '0.25', '-f', 'null', '-'], timeout=10)
observations['audio_probe'] = result
if result['exit_code'] != 0 or result['error']: blockers.append('Selected audio capture probe failed')
return {'schema_version': 1, 'ready': not blockers, 'blockers': blockers,
'settings': settings, 'package': identity, 'package_root': str(package),
'host': {'system': platform.system(), 'release': platform.release(),
'machine': platform.machine(), 'session_type': os.environ.get('XDG_SESSION_TYPE'),
'display_env_present': bool(os.environ.get('DISPLAY')),
'wayland_env_present': bool(os.environ.get('WAYLAND_DISPLAY'))},
'observations': observations, 'checked_utc': utc_now(),
'runtime_version_gaps': ['SDL runtime version and active GPU/driver/Vulkan instance require actual game logs'],
'acceptance': {'state': 'open', 'remaining': ['Preflight is not gameplay or audiovisual review']}}
def _stop(process):
"""Signal only a child we own; escalate its own process group after grace."""
try:
process.send_signal(signal.SIGINT)
process.wait(timeout=5)
except subprocess.TimeoutExpired:
try: os.killpg(process.pid, signal.SIGKILL)
except ProcessLookupError: pass
process.wait(timeout=5)
except ProcessLookupError:
pass
def run_capture(package, output, session_id, case_id, scope, settings, seconds=120,
tooling=False, probe=command_probe, popen=subprocess.Popen):
_id(session_id); _id(case_id)
if len(session_id) > 88: raise ValueError('Session ID must leave room for receipt suffix')
protocol = read_json(PROJECT / 'docs/evidence/scenarios.json')
if case_id not in {c['id'] for c in protocol['cells']} or scope not in protocol['obligations']:
raise ValueError('Unknown matrix case or obligation')
if not isinstance(seconds, (int, float)) or not math.isfinite(seconds) or not 1 <= seconds <= MAX_SECONDS:
raise ValueError('Capture duration must be 1..3600 seconds')
package = Path(package).resolve(strict=True)
output = Path(output).absolute()
if any(p.is_symlink() for p in (output, *output.parents)):
raise ValueError('Capture output cannot use symlink aliases')
separated_roots(package, output); separated_roots(PROJECT.parent / 'Original', output)
if output.exists(): raise ValueError('Capture output must be fresh; use a new session ID')
report = preflight(package, settings, tooling, probe)
output.mkdir(parents=True)
_write_json(output / 'preflight.json', report)
identity_dir = output / 'identity'; identity_dir.mkdir()
if report['package']:
for name in ('GamePort', 'fidelity-build.json', 'BUILD-INFO.txt'):
shutil.copyfile(package / name, identity_dir / name)
_write_json(identity_dir / 'resources.json', report['package']['resources'])
shutil.copyfile(Path(__file__), identity_dir / 'collector.py')
start, wall_start = time.monotonic(), utc_now()
game = [str(package / 'GamePort'), '--assets', str(package / 'assets'),
'--load-save', str(package / 'assets/NewGame.tsk'), '--walk',
'--fidelity-output', str(output / 'observer'), '--fidelity-session', session_id,
'--fidelity-case', case_id]
recorder = ['ffmpeg', '-nostdin', '-hide_banner', '-n', '-f', 'x11grab',
'-framerate', '30', '-video_size', settings['size'], '-i',
settings['display'] + '+' + settings['offset'], '-f', 'pulse', '-i',
settings['audio_source'], '-t', str(seconds), '-vf', 'freezedetect=n=-60dB:d=2',
'-c:v', 'ffv1', '-c:a', 'pcm_s16le', '-fs', str(MAX_MEDIA), str(output / 'raw.mkv')]
state = {'schema_version': 1, 'session_id': session_id, 'launch_id': session_id,
'clock_id': session_id + '-monotonic', 'case_id': case_id, 'scope': scope,
'package_root': str(package), 'tooling_only': tooling,
'input_method': settings['input_method'], 'settings': settings,
'invocation': {'argv': game, 'cwd': str(package)}, 'recorder_argv': recorder,
'clocks': {'monotonic_start': start, 'monotonic_end': start,
'wall_start': wall_start, 'wall_end': wall_start},
'status': 'failed' if not report['ready'] else 'incomplete',
'missing': list(report['blockers']), 'processes': {}}
_write_json(output / 'started.json', state)
processes = []
try:
if report['ready']:
env = dict(os.environ, DISPLAY=settings['display'], SDL_VIDEODRIVER='x11')
if not tooling and (env.get('SDL_AUDIODRIVER') in ('dummy', 'disk') or env.get('SDL_VIDEODRIVER') == 'dummy'):
raise ValueError('Dummy SDL devices cannot be used for native capture')
# Explicit source matches the selected real Pulse system, not a dummy inherited backend.
env['SDL_AUDIODRIVER'] = 'pulseaudio'
with (output / 'recorder.log').open('xb') as recording_log, (output / 'game.log').open('xb') as game_log:
recording = popen(recorder, cwd=output, env=env, stdout=recording_log,
stderr=subprocess.STDOUT, start_new_session=True)
processes.append(recording)
child = popen(game, cwd=package, env=env, stdout=game_log,
stderr=subprocess.STDOUT, start_new_session=True)
processes.append(child)
# One deadline covers both children. Logs/media are checked every wait slice.
deadline = time.monotonic() + seconds + 3
for name, child_process in (('game', child), ('recorder', recording)):
while True:
if any(p.stat().st_size > MAX_LOG for p in (output / 'game.log', output / 'recorder.log')):
raise ValueError('Capture log exceeds 32 MiB bound')
remaining = deadline - time.monotonic()
if remaining <= 0: raise subprocess.TimeoutExpired(game, seconds)
try:
code = child_process.wait(timeout=min(1, remaining))
state['processes'][name] = code
break
except subprocess.TimeoutExpired:
# Doubles and real processes both expose poll; timeout at the
# total deadline remains an abort, never a captured outcome.
if child_process.poll() is not None:
raise
state['status'] = 'captured' if all(c == 0 for c in state['processes'].values()) else 'failed'
if state['status'] == 'failed': state['missing'].append('Game or recorder exited unsuccessfully')
except (KeyboardInterrupt, subprocess.TimeoutExpired):
state['status'] = 'aborted'; state['missing'].append('Capture interrupted or duration deadline exceeded')
except (OSError, ValueError) as error:
state['status'] = 'failed'; state['missing'].append(str(error))
finally:
for process in processes:
if process.poll() is None or state['status'] == 'aborted': _stop(process)
state['clocks'].update(monotonic_end=time.monotonic(), wall_end=utc_now())
_write_json(output / 'session.json', state)
return state
def collect(run, probe=command_probe, annotations=None):
run = Path(run).resolve(strict=True)
state, pre = read_json(run / 'session.json'), read_json(run / 'preflight.json')
if (run / 'receipt.json').exists(): raise ValueError('Receipt already finalized; preserve history')
missing = list(state['missing'])
if pre['package']:
try:
current = _package(Path(state['package_root']), 'linux-x64', state['tooling_only'])
if current != pre['package']: raise ValueError('Package changed since launch')
except (ValueError, OSError) as error:
missing.append('Post-capture package identity failed: ' + str(error))
media = run / 'raw.mkv'
duration = None
if media.exists() and media.stat().st_size:
media_probe = probe(['ffprobe', '-v', 'error', '-show_streams', '-show_format',
'-of', 'json', str(media)], timeout=20)
_write_json(run / 'media-probe.json', media_probe)
try:
payload = json.loads(media_probe['stdout'])
duration = float(payload['format']['duration'])
roles = {s.get('codec_type') for s in payload['streams']}
if media_probe['exit_code'] != 0 or media_probe['error'] or not math.isfinite(duration) or duration <= 0:
raise ValueError('Invalid media duration/probe')
if not {'video', 'audio'}.issubset(roles): raise ValueError('Missing video/audio streams')
except (ValueError, KeyError, TypeError) as error:
missing.append('Media inspection failed: ' + str(error)); duration = None
else:
missing.append('Raw video/audio recording missing or empty')
log = run / 'recorder.log'
if log.exists():
if log.stat().st_size > MAX_LOG: missing.append('Recorder log exceeds bounded inspection')
elif 'freeze_start' in log.read_text(errors='replace'):
missing.append('Possible frozen media indicator requires actual visual inspection')
if not (run / 'observer').exists(): missing.append('Passive observer/input events unavailable')
identity = {}
identity_dir = run / 'identity'
if pre['package']:
for key, name in (('executable', 'GamePort'), ('package', 'fidelity-build.json'),
('source', 'BUILD-INFO.txt')):
identity[key] = {'path': 'identity/' + name, **identify_file(identity_dir / name)}
identity['resources'] = {'path': 'identity/resources.json', **identify_file(identity_dir / 'resources.json')}
identity['launcher'] = {'path': 'identity/collector.py', **identify_file(identity_dir / 'collector.py')}
artifacts = []
for path in sorted(run.rglob('*')):
if path.is_symlink(): raise ValueError('Symlink in capture output')
if not path.is_file() or path.is_relative_to(identity_dir): continue
name = path.relative_to(run).as_posix()
role = 'video' if name == 'raw.mkv' else 'input_events' if name.startswith('observer/') else 'diagnostic'
item = {'path': name, 'role': role, **identify_file(path)}
if state['tooling_only']: item['synthetic'] = True
if name == 'raw.mkv' and duration is not None: item['duration_seconds'] = duration
artifacts.append(item)
# The same hashed MKV contains both streams; audio role uses a distinct
# byte-identical local alias to satisfy the shared validator's unique paths.
if duration is not None:
shutil.copyfile(media, run / 'raw-audio.mkv')
artifacts.append({'path': 'raw-audio.mkv', 'role': 'audio',
'duration_seconds': duration, **identify_file(run / 'raw-audio.mkv'),
**({'synthetic': True} if state['tooling_only'] else {})})
events = []
if annotations:
note = read_json(annotations)
events = note.get('events', [])
# Annotations carry observed markers, never review/acceptance promotion.
kind = 'synthetic' if state['tooling_only'] else 'native_port' if state['input_method'] == 'physical' else 'port_fixture'
status = state['status']
if status == 'captured' and missing: status = 'failed'
receipt = {'schema_version': 1, 'receipt_id': state['session_id'] + '-linux',
'session_id': state['session_id'], 'case_id': state['case_id'], 'scope': state['scope'],
'evidence_kind': kind, 'historical': False, 'status': status,
'platform': {'os': 'linux', 'execution': 'native' if kind == 'native_port' else kind},
'invocation': state['invocation'], 'clocks': state['clocks'], 'identity': identity,
'artifacts': artifacts, 'derivatives': [], 'events': events,
'limitations': ['Collection does not prove visible moving gameplay, physical input or audible output',
'Existing NewGame.tsk entry is not a reconstructed main menu',
'Observer and recording overhead remains part of this identified run'],
'missing_evidence': missing, 'review': {'visible': False, 'audible': False,
'ordinary_input': False, 'human_reviewed': False},
'capture_methods': state['settings'], 'clock_id': state['clock_id'],
'launch_id': state['launch_id'],
'acceptance': {'state': 'open', 'remaining': [
'Actual moving-content/crop/clock/physical-input/audibility review',
'Observed scenario markers and lifetime/route continuity validation',
'Original-DxWnd and native Windows comparison']}}
validate_receipt(receipt, run)
_write_json(run / 'receipt.json', receipt)
return receipt
def main():
parser = argparse.ArgumentParser(description=__doc__)
sub = parser.add_subparsers(dest='action', required=True)
for action in ('preflight', 'run'):
command = sub.add_parser(action)
command.add_argument('--package', type=Path, required=True)
command.add_argument('--settings', type=Path, required=True)
if action == 'run':
command.add_argument('--output', type=Path, required=True)
command.add_argument('--session-id', required=True)
command.add_argument('--case-id', required=True)
command.add_argument('--scope', required=True)
command.add_argument('--seconds', type=float, default=120)
command = sub.add_parser('collect')
command.add_argument('--run', type=Path, required=True)
command.add_argument('--annotations', type=Path)
command.add_argument('--import-to', type=Path)
args = parser.parse_args()
if args.action == 'preflight':
result = preflight(args.package, read_json(args.settings))
elif args.action == 'run':
result = run_capture(args.package, args.output, args.session_id, args.case_id,
args.scope, read_json(args.settings), args.seconds)
else:
result = collect(args.run, annotations=args.annotations)
if args.import_to: import_receipt(args.run / 'receipt.json', args.run, args.import_to)
print(canonical_bytes(result).decode(), end='')
return 0 if result.get('ready', result.get('status') == 'captured') else 1
if __name__ == '__main__':
raise SystemExit(main())