Qoresence

Gaming Streaming Observatory Engine — local-first, one clock, many glasses.

Qoresence turns HDMI video, DualSense HID, and game situation into a single causal event bus, then surfaces it through Sight Glass (Aperture Glass), native Retina Monitor, local HDMI clips, and AgentGlass / MCP. Chat, heat, and score digits are licensed by the shared clock plus tickets — not by coworker personas. The capture card is the brain; everything else is a glass. Twitch is not a product route.

What it is	What it is not
Observation of HDMI + DualSense on one monotonic clock	Anti-cheat, humanity, or eligibility claims
Co-occurrence, coupling, presence evidence	Live path into QorTroller / PoAC / `*-truth`
Empty glyphs (`□–□`) and DualSense-on-PS5 emptiness	Invented `0–0`, last-good overlay, PAD WAIT as failure
Local MP4 + button / coupling / OTel sidecars	Dual-opening the same capture card
Optional research wrap onto `qoresence-research` with a grant	On-chain by default

Docs: GitHub Pages · Install guide · Wiki · Download

Qoresence Live 0.9.0 — local observatory for X. Public face: X @Qoresence. Brain stays on your machine. Live pixels: OBS → X Live Studio (recipe). VOD / Timeline receipts: future X API via default-off X Glass — not shipped (docs/X_GLASS.md). Do not claim --x-glass ships.

Every lobe is OFF until you opt in.

What makes it novel

Idea	Why it matters
One brain → N glasses	Situation + events once; Lens (OBS), Sight Glass, Session Theater, Mobile Glass, Monitor, Stem are views
Ticket-clock	Coupling ticket licenses heat / pad–picture join. Confirm ticket + `score_vlm_locked` licenses digits. Actuators: Aperture / Bind / License / Arm — not Agent Society coworkers
Aperture Glass	One visual system: Sight Glass SPA + public GitHub Pages. Flat void, machined iron, HOLD glyphs. Never fake LIVE on the site
Fail-closed speech	Unlocked scores stay empty. DualSense on the PS5 (no laptop HID) is success, not PAD WAIT. Same-Seq: widgets match the LIVE frame or they go dark
Session Theater	`/session.html` — Now + Story + Recap over a fail-closed normalized pack; live `GET /api/session/view` and `/api/session/recap`; Open clip only for validated existing MP4s
CIVIF	Coupled Input–Video Intelligence Framework. Live ticks + clip records; `/civif.html` and `GET /api/civif/live`. Session Theater is a query over that pack — not a second capture
Title-presence	Optical title lock with a hard `plane` tag; on with `--play`; menu/pause fail-closed; does not yank an explicit `--game-profile`
Qoresence owns the card	Physical HDMI has one owner — Qoresence Streamer; OBS uses Browser Source for Lens only (no dual-open)
FrameHub (no second capture)	Streamer already holds BGR frames; monitor + IVC subscribe — never dual-open DShow
Input–Video Coupler (IVC)	DualSense edges join `clock_ns` / `frame_seq` for co-occurrence coupling (observation only)
Ghost Stick	Pad locus painted on the HDMI frame it belongs to. Default ON under `--play`. Veto when Same-Seq / coupling drops
Two-speed ClutchBot	`path=fast` video+input soft acts; OCR + DeepSeek vision is `path=confirm` referee (never invents scores on fast)
A2A bus (optional)	Quicksilver scene/chat under local policy; does not replace OCR / confirm tickets
Local HDMI Foundry	True capture-ring clips (`clips/*.mp4`) + `.buttons.json` / `.coupling.json` / `.otel.json` sidecars
Foundry RAG	Search past clips by chapter/buttons/graph/timeline — software-only, no capture needed
OpenTelemetry (optional)	Causal bus traces + metrics; per-clip sidecars — local OTLP, default OFF. Exporter may only enqueue
Causal event bus	Every event carries `session_id` + `clock_ns` + `source_lobe`
TypeSafe Jev + OCCF	Typed snap judgments (`typesafe` CLI / SDK) feed an opt-in judgment ledger and a pull-only observatory MCP. Agents speak licensed tokens only; `licenses_digits=false` forever — never mint score digits

Language: co-occurrence / coupling / presence evidence — not legitimacy verification.

Architecture (novel stack)

 PS5 HDMI → capture card (physical DShow, e.g. USB3.0 Video)
        │
        ▼
 ┌────────────────────────────────────────────────────────────┐
 │   StreamerRuntime OWNS card  (--streamer-device 0)          │
 │   clip_buffer · FrameHub · OCR / DeepSeek vision · Foundry │
 └───────┬──────────────────────────────┬─────────────────────┘
         │                              │
         ▼                              ▼
  Deck LIVE (Aperture Glass SPA) DualSense-on-PS5 (empty laptop HID = success)
  Session / Mobile / Monitor     optional: DualSense USB here → InputRing → IVC
  Ghost Stick on Same-Seq LIVE
         │                              │
         └──────────┬───────────────────┘
                    ▼
             RetinaEventBus → Situation / title-presence / tickets / ClutchBot / AgentGlass / MCP
                    │
    Coupling ticket  → heat / pad–picture (fast)
    Confirm ticket   → score digits (confirm + score_vlm_locked)
                    │
    OBS (optional stream): Browser Source ONLY
    http://127.0.0.1:8765/overlay.html  — do NOT open the same physical card
    Audience live to X (optional): OBS Custom RTMP → X Live Studio
      — not a Qoresence encoder; see docs/X_LIVE_STUDIO.md · product face docs/X_GLASS.md
    Deck:     http://127.0.0.1:8765/deck.html
    Session:  http://127.0.0.1:8765/session.html  (Now + Story + Recap; not HDMI)
    CIVIF:    http://127.0.0.1:8765/civif.html
    Phone:    http://127.0.0.1:8765/mobile.html  (LAN: --deck-bind 0.0.0.0 + scan QR)

Planes

Plane	Default	Role
Capture	Opt-in per lobe	Streamer, controller, screen, outcome, visual
Situation	With `--play`	Score, down, clutch context — digits only when confirm-licensed
Operator glass	`--deck` / `--monitor`	Aperture Glass Theater, Session Theater, Lens, Mobile Glass, native monitor
Clutch (local)	`--play`	Deck feed + local HDMI clips (Twitch leftover, default-OFF)
Stem	conductor on `--play`	Situation-directed program; `--stem-program` / `--stem-audio` / `--stem-record` default OFF
Spectator	`--agent-glass`	HTTP/WS API + MCP for AI agents
Optional social	Off	X is the named public glass. Live: OBS → X Live Studio. Timeline VOD = default-off X Glass (not shipped) — future X API receipts (docs/X_GLASS.md). Twitch leftover stays OFF
Society	`--agent-society`	Leftover stub. Default OFF. `--play` does not enable. Actuators, not coworkers
Research	Off	Fusion, trio-retina / WASM, Streamr plugin

Recent milestones (shipped on `main`)

Theme	What landed
Aperture Glass + Pages	One chrome for Deck SPA and GitHub Pages. HOLD command bar, theater Watch, 6m45s NCAA 27 demo. Never fake LIVE on the public site (#125). Public face: X @Qoresence
Ticket-clock + confirm remint	Coupling ticket licenses heat; confirm ticket + `score_vlm_locked` licenses digits. Same `ticket_id` reused across DAL/Dallas/empty flicker (#116)
Quicksilver confirm path	Scoreboard / observation vision is `qwen3.7-flash` on the same Quicksilver API + clutchbot key as ClutchBot chat. Not Gemini. `muse-spark-1.3` is chat-only (JPEG crop is 400 `model_not_found`). JPEG crop in, JSON scorebug out
Ghost Stick	Default ON under `--play`. DualSense locus on the HDMI frame it belongs to. Same-Seq veto (`docs/GHOST_STICK.md`)
Empty HID is success	DualSense stays on the PS5. No laptop HID is not PAD WAIT (TCBS). Bind owns DualSense↔HDMI join
MatchAgent	Opt-in observer (`--match-agent` / `QORESENCE_MATCH_AGENT=1` on operator launchers). Fail-closed `last_note` on Clutch Feed. DualSense stays on the PS5
Aperture Glass Theater	Viewport HUD, Clutch Feed rail, licensed SituationCard, hid_by_seq press chip, observatory instrument. SPA served at existing Deck URLs
Seeing-path ConfirmTicket	Unlicensed HUD digits never serialize. First-class `cfb_27` / Madden HUD crops even when `game_state` is menu (#108 / #110). Identity swap does not invent 0–0
HID log-once	Classify HID domain once per transport — not 1 kHz INFO that freezes the capture thread (#117)
CIVIF	Live coupled ticks + clip records; `/civif.html`. Score digits only when `board_locked`. Empty HID on this host is valid (`docs/CIVIF.md`)
Session Theater	`/session.html` Now + Story + Recap; `GET /api/session/view` + `/api/session/recap`; fail-closed score/HID; validated `hdmi_clip_*` Open clip
Mobile Glass + QR	`/mobile.html` FrameHub WebRTC (MJPEG fallback); Theater copy-link + QR when `--deck-bind 0.0.0.0`
Title-presence	Hysteresis wrap on `GameAutoDetector`; on with `--play`; `--game-profile` pin honored
Deadlock hardening	Re-entrancy guard in A2A + presence; OTel subscribe may only enqueue; `tests/test_deadlock_regression.py`
OpenTelemetry	`--otel` causal bus traces + coupling metrics; `.otel.json` / `.coupling.json` clip sidecars; Jaeger on localhost
MCP universal glass	12 tools including fail-closed `get_observation` and grant-gated `wrap_observation` (`qoresence-research` only)
SEQGATE + memory	Same frame or silence (`docs/SEQGATE.md`). Session-brain writes need a FrameHub stamp; stale memory cannot license digits (`docs/SEQGATE-Memory-Wiring.md`)
SEQGATE crop honesty	ConfirmTicket publishes `confirm_clock_ns` + `ticket_crop_hash` into AgentGlass; SEQGATE compares the ticket scorebug crop, not FrameHub hub crop — remint no longer false `crop_mismatch` / sticky `ticket_stale`
TypeSafe Jev	Typed noul / choice / score judgments via TypeSafe — not fragile LLM parse. Auth: `typesafe auth status` → has_key only (never print keys)
Jev ledger v0	Unified append-only `logs/jev_ledger.jsonl` (`qoresence.jev.ledger.v0`). Opt-in `--jev` / `--jev-ledger`. Dual-write from judgment packs; unknown pack fails closed
OCCF connector bind	Agent turn ↔ observatory instant as ledger `pack=connector` (`--jev-connector`). Guest clock never stamps `clock_ns`. Muse first; agent-generic
OCCF MCP	Pull-only `qoresence.mcp.occf`: `get_observation` / `refuse_actuator` / `refuse_mid_drive_publish`. Opt-in `QORESENCE_OCCF=1` / `--occf`. Score claim token only — digits never echoed
Foundry RAG	`search_clips` / `get_drive_graph` searchable session memory — software-only, no capture card

Docs for each: SESSION_THEATER · CIVIF · GHOST_STICK · TWO_SPEED_CLUTCHBOT · PLAY_PHRASE_COUPLING_TICKET · MOBILE_GLASS · TITLE_PRESENCE · WEBRTC_LIVE · OBS_OWNS_CARD · X_LIVE_STUDIO · X_GLASS · RETINA_MONITOR · CONTROLLER_VIDEO_SYNC · OTEL · SEQGATE · SEQGATE-Memory-Wiring · ROADMAP · PILOT_SESSION · PILOT_MONITOR

Capture: Qoresence owns the card

One physical HDMI/DShow device → one owner, and that owner is Qoresence. OBS never opens the capture card; it only gets the overlay as a Browser Source (http://127.0.0.1:8765/overlay.html). Full guide: docs/CAPTURE_OWNERSHIP.md

Job	Who does it
Open the physical capture card	Qoresence (`--streamer-device`, e.g. `0`)
Show the score overlay on stream	OBS Browser Source → `http://127.0.0.1:8765/overlay.html`
Anything in OBS on the same card	Nothing — remove any Video Capture Device that points at the card

python -m qoresence.cli --streamer-list
# Remove the physical card from OBS first, then:
python -m qoresence.cli --play --deck --monitor --agent-glass --streamer-fps 60

The older "OBS owns the card → Virtual Camera" setup (legacy Pattern A) is no longer the recommended path; it is kept only in docs/CAPTURE_OWNERSHIP.md for reference.

Download and install (Windows)

The recommended user path is the versioned Windows starter package published on GitHub Releases. It includes the source, local installer, Deck/AgentGlass/MCP stack, pilot docs, and a launcher. Python 3.11+ is required; the installer creates a local .venv and does not include capture-card drivers or secrets.

Download the latest Windows package
Windows installation guide
Verify the SHA-256 file beside the ZIP when downloading a release.

# From the extracted Qoresence folder
powershell -ExecutionPolicy Bypass -File .\Install-Qoresence.ps1
.\Start-Qoresence.bat

Getting scores

Qoresence only shows a score when it is sure. When it is not sure, the score stays blank. It never guesses.

Madden NFL 27 works without a key. A built-in local reader reads the score, game clock and quarter straight from the standard Madden scorebug on your capture card. It runs on your PC with no account, no API key and no upload. It needs the same reading on several frames in a row before it shows anything.
The local reader stays blank when it is unsure. That includes scorebug styles it has not learned yet (for example the dark primetime look), digits it has not learned yet (today: the digit 8), banners or replays covering the score, the red clock in the final seconds, and overtime. Blank is the safe answer, not a bug.
College Football 27 and the cloud reader need a QuicksilverPro key for now. With a key set, Madden still uses the local reader first and the cloud read double-checks it. If the two disagree, the score stays blank.
Turn the local reader off with QORESENCE_LOCAL_SCOREBUG=0 (or force it on with =1). Details: qoresence/vision/local_scorebug/README.md.

Quickstart (Windows-first pilot)

git clone https://github.com/ConWan30/Qoresence.git
cd Qoresence
pip install -e ".[pilot]"   # capture, Deck, Monitor, AgentGlass/MCP, Windows discovery
python scripts/pilot_preflight.py

# Pattern B: Close OBS Video Capture on the physical card (no dual-open)
python -m qoresence.cli --streamer-list
python -m qoresence.cli --play --deck --monitor --streamer-fps 60
# Or double-click qoresence.bat (defaults: --play --deck --monitor --tray --a2a --controller --streamer-fps 60;
# MatchAgent via QORESENCE_MATCH_AGENT=1 on this launcher only — --play itself does not enable it)

# OBS (optional stream): Browser Source only → http://127.0.0.1:8765/overlay.html
# Audience to X: OBS Custom RTMP → X Live Studio (docs/X_LIVE_STUDIO.md). VOD receipts: future X Glass (docs/X_GLASS.md) — not shipped. Do not add the capture card in OBS.

URL	Glass
http://127.0.0.1:8765/deck.html	Sight Glass — Aperture Glass Theater (LIVE)
http://127.0.0.1:8765/session.html	Session Theater (Now + Story + Recap)
http://127.0.0.1:8765/civif.html	CIVIF live ticks / highlights (JSON ~1 Hz)
http://127.0.0.1:8765/api/session/view	Normalized live session envelope
http://127.0.0.1:8765/api/session/recap	Read-only `session-recap-1`
http://127.0.0.1:8765/overlay.html	Clutch Lens (OBS Browser Source)
http://127.0.0.1:8765/mobile.html	Mobile Glass (phone view; WebRTC / MJPEG)
http://127.0.0.1:8765/trace.html	Local OTel / coupling trace viewer
http://127.0.0.1:8765/video	LIVE MJPEG
http://127.0.0.1:8765/health	Capture + lock + ticket health (`age_s`, frames, `score_vlm_locked`)
http://127.0.0.1:8765/api/situation	Snapshot (+ `controller` when IVC on; digits only when locked)
http://127.0.0.1:8765/api/agent/snapshot	AgentGlass: curated state + coupling
http://127.0.0.1:8765/api/agent/events	AgentGlass: cursor-paginated events
http://127.0.0.1:8765/agent/stream	AgentGlass: live WebSocket stream

Verify live

# within ~10s of start — use Write-Host so PowerShell always shows a labeled line:
$h = Invoke-RestMethod http://127.0.0.1:8765/health
Write-Host "age_s=$($h.state.video.age_s)  frames=$($h.state.video.frames)  locked=$($h.state.situation.score_vlm_locked)"
# healthy: age_s < 1, frames climbing. Unlocked scores stay empty — that is success.

# open Deck (browser does not auto-open from CLI):
Start-Process http://127.0.0.1:8765/deck.html

Note: python -m qoresence.cli --play ... keeps running in that window (log lines only). Deck is a browser URL — it does not pop up by itself. Hard-refresh if the tab was open before restart.

Session notes: docs/PILOT_SESSION.md. While playing, python scripts/pilot_monitor.py writes logs/pilot/closeout_*.md (docs/PILOT_MONITOR.md). After the session stops, optional one-shot python -m qoresence.cli --logbook writes a short debrief from JSONL + chapters (docs/LOGBOOK.md; default OFF).

Gameplay eye: your TV or the Retina Monitor (--monitor), both fed by the card Qoresence owns. OBS is not a gameplay eye here — it only shows the Browser Source overlay. Shared clock_ns — not a stream-delay clock.

ClutchBot on --play is Deck feed + local HDMI clips. Twitch IRC/Helix is leftover code, default-OFF, not a launch path. Do not set --clutchbot-channel for the local pilot.

AgentGlass + MCP (optional)

Any MCP-compatible AI (Cursor, Claude, etc.) can query Qoresence over stdio.

# run Qoresence with the spectator glass
.\qoresence.bat --play --deck --agent-glass --streamer-fps 30

# list tools
qoresence-mcp --help-tools

# add to Cursor / Claude Desktop mcp.json
{
  "mcpServers": {
    "qoresence": {
      "command": "python",
      "args": ["-m", "qoresence.mcp.server"],
      "env": { "QORESENCE_AGENT_GLASS_HOST": "127.0.0.1", "QORESENCE_AGENT_GLASS_PORT": "8765" }
    }
  }
}

Agents must call get_observation before they speak. Unlocked scores and localhost URLs stay silent. Wrap dest is qoresence-research only, and only with an operator grant.

For a stricter pull-only observatory surface aimed at personal agents (Muse first), see TypeSafe Jev + OCCF below — default OFF; --play does not enable it.

TypeSafe Jev + OCCF (optional)

What it is: typed snap judgments + a unified ledger + a fail-closed MCP so a personal agent can witness the session without inventing scores, taking the pad, or publishing mid-drive.

What it is not: a second truth plane, a DualSense driver, a digit mint, or something --play turns on by itself.

TypeSafe Jev — how it works

TypeSafe Jev answers structured questions (noul / choice / score) through the TypeSafe SDK / typesafe CLI. Qoresence packs call this for observation-plane gates instead of fragile “LLM prompt → parse JSON” loops.

Operator habit	Why
`typesafe auth status` → report has_key only	Keys stay out of chat / commits
Prefer `typesafe ask` with temp-dir state + questions	Typed answers, not free-form prose
Never print `TYPESAFE_*` or key files	Standing corps order

Inside the engine, Jev feeds judgment packs (ticket_stale, conductor, score plausibility, connector-bind classification, …). Python still owns compose — the model classifies; code decides deny / silent / act.

Hard laws (every layer):

Plane qoresence-observation only
licenses_digits is false on every payload, forever — Jev never mints score digits
DualSense stays on the PS5; the agent never takes the pad
Empty / unlocked → blank tokens and must_not_invent, never a guess

Judgment ledger (`qoresence.jev.ledger.v0`)

Unified append-only JSONL sink (default logs/jev_ledger.jsonl). Judgment packs keep any private JSONL and dual-write here so later slices (jev_tail, connector binds) query one file.

Flag / env	Default	Effect
`--jev-ledger` / `QORESENCE_JEV_LEDGER=1`	off	Enable the unified ledger
`--jev` / `QORESENCE_JEV=1`	off	Umbrella opt-in (enables ledger among Jev surfaces)
`--play`	—	Does not enable the ledger

Module: qoresence/observability/jev_ledger.py
Unknown pack → rejected, nothing written
Append is best-effort and never raises into a pack hot path

Connector bind (`qoresence.connector-bind.v0`)

Correlates one personal-agent turn to one observatory instant. Binds exist only as ledger rows with pack="connector" — there is no connector.jsonl.

Flag / env	Default	Effect
`--jev-connector` / `QORESENCE_JEV_CONNECTOR=1`	off	Enable bind engine (also ensures ledger on for these rows)

Guest clock is annotation only: asked_at_unix_ms never stamps observatory clock_ns
Sync methods (first match): live_pull → seq_match → chapter_id → recap_door → none
States: bound / unbound / stale / denied
TypeSafe door when a key is present; otherwise deterministic local_heuristic
Code-owned denies: pad / mid-drive publish / leave-localhost / actuator-or-exfil
Module: qoresence/observability/connector_bind.py

OCCF MCP (pull-only observatory connector)

Smallest localhost MCP for personal agents. Stdio only — pulls AgentGlass state; never opens capture.

# Opt in (also QORESENCE_OCCF=1). --play does not enable this.
python -m qoresence.mcp.occf --occf

# Cursor / Claude Desktop example
{
  "mcpServers": {
    "qoresence-observatory": {
      "command": "python",
      "args": ["-m", "qoresence.mcp.occf", "--occf"],
      "env": { "QORESENCE_OCCF": "1" }
    }
  }
}

Tool	Role
`get_observation`	Witness read: `may_say` / `must_not_invent`. Optional `jev_tail` (token-only ledger rows). Optional `agent_turn` for connector bind
`refuse_actuator`	Closed deny — pad / DualSense / capture control (`pad_not_on_this_plane`)
`refuse_mid_drive_publish`	Closed deny — publish / share / upload mid-drive

Score digits are never echoed: when the board is licensed, OCCF reports score.claim=true with home/away null and redacts score-pair strings (e.g. speech) to □–□. Integers stay on the ConfirmTicket, not on this API.

Contract lives in qoresence/mcp/occf.py (and related observability modules). Full OCCF design notes may land under docs/ later — until then, trust the module docstrings over rumor.

SEQGATE honesty (related)

SEQGATE still means same frame or silence (docs/SEQGATE.md). Crop honesty on top:

ConfirmTicket mint/remint publishes confirm_clock_ns + ticket_crop_hash into AgentGlass.
SEQGATE / seeing-path compare the ticket scorebug crop, not FrameHub’s hub crop — so a remint is not falsely crop_mismatch / sticky ticket_stale.

Memory wiring: docs/SEQGATE-Memory-Wiring.md.

Components

Core · Lobes · Sync · Monitor · Deck · Agents

Path	Role
`qoresence/core/`	Session, `RetinaEventBus`, unified config, types
`qoresence/lobes/`	streamer, controller, screen, outcome, visual
`qoresence/sync/`	InputRing, Input–Video Coupler
`qoresence/monitor/`	FrameHub, OpenCV Retina Monitor
`qoresence/vision/clip_buffer.py`	HDMI ring + Foundry export + buttons sidecar
`qoresence/deck/`	FastAPI Deck, overlay, LIVE, clip API (serves Aperture Glass SPA)
`glass/`	Sight Glass / Session Theater SPA source (Aperture Glass)
`qoresence/agents/`	SituationModel, MomentScorer, ClutchBot, MatchAgent, AgentGlass, MCP
`qoresence/mcp/`	Universal AgentGlass MCP + opt-in OCCF observatory MCP (`occf.py`)
`qoresence/observability/`	OTel exporter (enqueue-only); Jev ledger, connector bind, TypeSafe ask helpers
`qoresence/fusion/`	Presence fusion (optional)
`qoresence/trio/`	trio-retina WASM validation (optional)

All lobes default enabled = False.

CLI flags (high signal)

Flag	Default	Effect
`--play`	off	Streamer + visual(local) + outcome + ClutchBot backends + deck wiring
`--game-detect`	on with `--play`/`--stream`	Incumbent `GameAutoDetector` (`--no-game-detect` to opt out)
`--title-presence`	on with `--play`/`--stream`	Optical title hysteresis + `plane` tag (`--no-title-presence` to opt out)
`--game-profile`	`ncaa_football_27`	`madden_27` (Madden NFL 27 + local NFL roster), `ncaa_football_27`, CoD / Valorant / Apex / Fortnite
`--deck`	off	Sight Glass HTTP/WS on `:8765`
`--deck-bind`	unset (host `127.0.0.1`)	Opt-in LAN listen (`0.0.0.0`) for `/mobile.html` phone glass
`--monitor`	off	Native FrameHub window
`--stem-program`	off	Stem Program-out (implies `--monitor`; replaces OBS Preview)
`--stem-audio`	off	Capture-card audio only; never a laptop mic
`--stem-record`	off	Session mux to `clips/stem_*.mp4` (disk; not a 1.0 gate)
`--controller`	off	DualSense HID + InputRing + IVC. DualSense-on-PS5 emptiness is valid
`--ghost-stick`	on with `--play`	Pad locus on Same-Seq LIVE. `--no-ghost-stick` / `QORESENCE_GHOST_STICK=0` to opt out
`--match-agent`	off	Match observer via Quicksilver muse-spark-1.3. Also `QORESENCE_MATCH_AGENT=1` on `qoresence.bat`
`--tray`	off	System tray score / sync chip. On by default when you double-click `qoresence.bat`
`--streamer-device N`	-1	Auto physical card by name; or fixed index. Point it at the physical card (OBS Virtual Camera only for the legacy Pattern A setup)
`--clutchbot` / leftover Twitch flags	off	Deck feed is already on with `--play`. Channel/token flags are leftover IRC/Helix — not the local route
`--agent-glass`	off	HTTP/WS spectator API (MCP-ready)
`--agent-society`	off	Leftover Society stub; opt-in only — `--play` does not enable
`--a2a`	off	Quicksilver scene/chat under local policy. Does not replace confirm tickets
`--jev` / `QORESENCE_JEV=1`	off	Umbrella opt-in for Jev surfaces (ledger among them). `--play` does not enable
`--jev-ledger` / `QORESENCE_JEV_LEDGER=1`	off	Unified judgment ledger JSONL (`logs/jev_ledger.jsonl`)
`--jev-connector` / `QORESENCE_JEV_CONNECTOR=1`	off	OCCF agent↔session bind rows on the ledger
`--occf` / `QORESENCE_OCCF=1`	off	Pull-only observatory MCP (`python -m qoresence.mcp.occf`). `--play` does not enable
`--otel`	off	Causal traces + metrics to local OTLP; clip sidecars; Jaeger on `:16686`

What it does / doesn't

Does	Does not
Observe frames + HID + game situation	Claim humanity / eligibility
Join inputs to video by shared clock + tickets	Anti-cheat / legitimacy “proof”
Empty glyphs and DualSense-on-PS5 emptiness	Invent 0–0 or treat empty HID as PAD WAIT
Local MP4 + button / coupling / OTel sidecars	Dual-open the same capture card
Overlays, Deck, local Foundry clips	Store biometrics in the cloud by default
Optional research trio-retina / Streamr	Require on-chain, Twitch, or Agent Society for MVP

Data & privacy

Path	Default
Frames / clips / timeline	Local disk (`clips/`, `logs/`) — observation plane only
Leftover Twitch IRC/Helix	Not a product route. Only if you still set channel + tokens
Quicksilver / DeepSeek vision	Optional: scoreboard VLM + A2A when enabled — crops / metadata, not continuous 60 fps upload by design
Deck bind	`127.0.0.1` only (not `0.0.0.0`)
Claims	No anti-cheat / legitimacy / “proof of humanity”

  HDMI card → Qoresence (local)
       ├─ FrameHub / Monitor / Deck LIVE   (stay on machine)
       ├─ clips/*.mp4 · logs/              (local)
       └─ optional: Quicksilver VLM/A2A (opt-in). Leftover Twitch IRC is not the local route.

Revoke / stop

Stop the CLI (Ctrl+C)
Leftover Twitch: if you ever set channel + tokens, revoke the app token in the Twitch developer console
Keys: remove or ignore .secrets/* (gitignored)
Artifacts (optional): delete clips/ and logs/ if you do not want local session residue

Documentation map

Doc	Topic
docs/ARCHITECTURE.md	Core design
docs/CAPTURE_OWNERSHIP.md	Qoresence owns the card; OBS = Browser Source overlay only (legacy Pattern A kept for reference)
docs/OBS_OWNS_CARD.md	Extended capture operator detail (despite the old file name, it describes the Qoresence-owns-the-card setup)
docs/X_LIVE_STUDIO.md	Audience live to X via OBS Custom RTMP (not a Qoresence encoder)
docs/X_GLASS.md	Live 0.9.0 product face — default-off X Glass (not shipped); VOD receipts = future X API
docs/PILOT_SESSION.md	CFB pilot runbook + notes
docs/PILOT_MONITOR.md	P0 evidence recorder while you play
docs/NFL_ROSTER.md	Madden 27 local NFL team/player names (nflverse)
docs/WEBRTC_LIVE.md	WebRTC LIVE from FrameHub (optional)
docs/RETINA_MONITOR.md	Native monitor / FrameHub
docs/OTEL.md	OpenTelemetry traces, metrics, and clip sidecars
docs/CONTROLLER_VIDEO_SYNC.md	IVC + InputRing
docs/TWO_SPEED_CLUTCHBOT.md	Fast video+input path; OCR confirm
docs/PRIORITY_INTEGRATIONS.md	Timeline · prediction lifecycle · clip chapters
docs/DRIVE_GRAPH.md	DriveGraph climax · fast↔confirm match · Why/chapters
docs/AGENT_GLASS.md	AgentGlass / MCP spectator API
docs/AGENT_SOCIETY.md	Leftover stub — actuators, not coworkers
docs/STEM.md	Retina Stem (conductor / program-out; not OBS)
docs/A2A_CLUTCHBOT.md	Quicksilver A2A bus (does not replace confirm tickets)
docs/RELEASE_HARDENING.md	CI localhost · latency · soak preflight
docs/GHOST_STICK.md	Ghost Stick on Same-Seq LIVE
docs/CIVIF.md	Coupled Input–Video Intelligence Framework
docs/DARK_THEATER_SAME_SEQ.md	Widgets match the LIVE frame or they go dark
docs/OPERATOR_BUS.md	Local Grok-bot mailbox (enqueue-only; not a lobe)
docs/PLAY_PHRASE_COUPLING_TICKET.md	SNAP/SPRINT/CUT/RELEASE → coupling ticket
docs/RETINA_DECK_UIUX.md	Lens / Rail / Theater
docs/clutchbot_setup.md	Leftover Twitch IRC/Helix (not the local route)
docs/STREAMR.md	Experimental Streamr plugin (default OFF)
docs/ROADMAP.md	Phases & versioning
docs/wiki/	Wiki source (mirrors GitHub Wiki)
docs/index.html	GitHub Pages landing (Aperture Glass)
docs/SEQGATE.md	Same frame or silence; ticket crop vs hub crop honesty
docs/SEQGATE-Memory-Wiring.md	Session-brain writes need FrameHub stamp; stale memory cannot license digits
`qoresence/observability/jev_ledger.py`	Judgment ledger schema + opt-in flags (module docstring)
`qoresence/observability/connector_bind.py`	OCCF connector-bind contract (module docstring)
`qoresence/mcp/occf.py`	Pull-only OCCF MCP tools + digit scrub laws (module docstring)
CONTRIBUTING.md	How to set up, test, and open PRs

Community: X @Qoresence · Email · Wiki · Discussions · Pages
(If wiki/discussions/pages are first-time, enable once under Settings — see docs/GITHUB_COMMUNITY.md.)

Testing

python -m pytest tests/ -q
python -m pytest tests/test_frame_hub.py tests/test_input_ring.py tests/test_ivc.py -q

# critical invariants: never break these
python -m pytest tests/test_deadlock_regression.py tests/test_otel_exporter.py tests/test_security_localhost.py tests/test_agent_glass.py tests/test_mcp.py -v

Project structure (short)

Qoresence/
├── docs/                 # Architecture, runbooks, wiki source, Pages
├── qoresence/
│   ├── core/             # Bus, session, config
│   ├── lobes/            # Capture lobes
│   ├── sync/             # InputRing + IVC
│   ├── monitor/          # FrameHub + Retina Monitor
│   ├── vision/           # clip_buffer, OCR, VLM helpers
│   ├── foundry/          # Clip ring + RAG search + DriveGraph
│   ├── deck/             # Operator theater + Lens (serves glass SPA)
│   ├── agents/           # ClutchBot, MatchAgent, AgentGlass, MCP
│   ├── mcp/              # AgentGlass MCP + opt-in OCCF observatory MCP
│   ├── observability/    # OTel + Jev ledger + connector bind
│   ├── fusion/           # Optional presence fusion
│   └── trio/             # Optional WASM path
├── glass/                # Aperture Glass SPA (Deck + Session Theater)
├── tests/
├── examples/             # AgentGlass / MCP examples
└── tools/obs/            # Virtual cam & overlay notes

License & principles

Observation plane by default; research modules opt-in
One physical DShow device → one owner
Ticket-clock: coupling licenses heat; confirm + score_vlm_locked licenses digits
Jev / OCCF: typed judgments + pull-only MCP; licenses_digits=false; opt-in only
Streamer decides which lobes run; leftover Twitch / Streamr / Society stay default-OFF
See repository LICENSE for terms

Built for operators who want local, auditable, multi-glass presence — not another delayed browser preview of the same card.

Name		Name	Last commit message	Last commit date
.github		.github
deploy		deploy
docs		docs
eval		eval
examples		examples
glass		glass
installer/windows		installer/windows
lab/x_live_01_crop_move		lab/x_live_01_crop_move
native		native
plugins/qoresence-observatory		plugins/qoresence-observatory
profiles		profiles
qoresence		qoresence
scripts		scripts
streamer-kit		streamer-kit
tests		tests
tools		tools
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
PRINCIPLES_AUDIT.md		PRINCIPLES_AUDIT.md
PRIVACY.md		PRIVACY.md
README.md		README.md
SECURITY.md		SECURITY.md
SYSTEM_PROMPT.md		SYSTEM_PROMPT.md
benchmark_results.json		benchmark_results.json
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
qoresence.bat		qoresence.bat
w3bstream_applet.wasm		w3bstream_applet.wasm
watch.bat		watch.bat

Navigation Menu

Repository navigation

About

Repository files navigation

Qoresence

What makes it novel

Architecture (novel stack)

Recent milestones (shipped on `main`)

Capture: Qoresence owns the card

Download and install (Windows)

Getting scores

Quickstart (Windows-first pilot)

Verify live

AgentGlass + MCP (optional)

TypeSafe Jev + OCCF (optional)

TypeSafe Jev — how it works

Judgment ledger (`qoresence.jev.ledger.v0`)

Connector bind (`qoresence.connector-bind.v0`)

OCCF MCP (pull-only observatory connector)

SEQGATE honesty (related)

Components

Core · Lobes · Sync · Monitor · Deck · Agents

CLI flags (high signal)

What it does / doesn't

Data & privacy

Revoke / stop

Documentation map

Testing

Project structure (short)

License & principles

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Qoresence

What makes it novel

Architecture (novel stack)

Recent milestones (shipped on main)

Capture: Qoresence owns the card

Download and install (Windows)

Getting scores

Quickstart (Windows-first pilot)

Verify live

AgentGlass + MCP (optional)

TypeSafe Jev + OCCF (optional)

TypeSafe Jev — how it works

Judgment ledger (qoresence.jev.ledger.v0)

Connector bind (qoresence.connector-bind.v0)

OCCF MCP (pull-only observatory connector)

SEQGATE honesty (related)

Components

Core · Lobes · Sync · Monitor · Deck · Agents

CLI flags (high signal)

What it does / doesn't

Data & privacy

Revoke / stop

Documentation map

Testing

Project structure (short)

License & principles

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Recent milestones (shipped on `main`)

Judgment ledger (`qoresence.jev.ledger.v0`)

Connector bind (`qoresence.connector-bind.v0`)