SnapNPlan Windows student monitor v2.2
====================================

Use the complete student_package generated by the teacher setup. The source
agent folder has no classroom configuration until the teacher builds a package.

One-time lab administrator setup
--------------------------------
If the trusted ZIP was downloaded, right-click the ZIP > Properties > Unblock
before extracting it. INSTALL-AGENT.bat asks Windows for administrator access.
The scripts use process-scoped RemoteSigned; school Group Policy still applies.
They do not change the machine's PowerShell execution policy.

Setup shows what it changes: installs files in C:\ProgramData\SnapNPlanAgent,
adds a visible monitor to each user's logon, enables the Windows DNS operational
channel, grants Users read access to that channel only, and disables Chrome/Edge
private DNS. It saves the original channel settings and browser policy values
in machine-backup.json for UNINSTALL-AGENT.bat. Restart the browsers afterward.

Each exam
---------
Sign in as the actual student. Run launch-exam.bat without administrator access.
The launcher starts the agent in that user's interactive desktop, then opens a
dedicated Chrome/Edge profile at the teacher's private IPv4 HTTP LAN address.
Chrome or Chromium-based Edge, whole-screen sharing, and successful local
browser-model inference are compulsory. The native monitor is required as a
separate layer; it cannot substitute for the browser model.

The local origin exception enables secure-context APIs for that exact teacher
origin including its port. The capture-source flag is a selection hint, not a
capability or model-readiness test. Use the exam page's share/start action,
share the ENTIRE screen, and wait for the browser model to load and successfully
run inference. A tab/window share, denied capture, missing browser capability,
or model failure must be corrected before exam entry. All model assets are
served by the teacher over the LAN. A user/session mutex prevents duplicate
native-agent instances.

The minimized monitor window and system-tray status icon are visible. Right-
click the icon to open current status, diagnostic logs, or stop the agent.
Stopping it makes the teacher see the PC as offline; it does not lock the PC.

v2.2 helper processes
---------------------
The monitor starts two small hidden helpers in the same student session:
- lease-heartbeat.ps1 tells the teacher every 3 seconds whether the monitor is
  alive and making progress. A busy monitor stays "online"; a frozen one is
  reported as stalled and shown offline; a stopped one ends the lease.
- screenshot-worker.ps1 captures, signs and uploads the evidence screenshots
  the teacher server requests, so a slow capture or upload never stalls the
  monitor. It takes no screenshot unless the server asks for one.
Both exit when the monitor exits. Shared code is in agent-runtime.ps1.

Exactly one display
-------------------
Only one screen can be shared and analysed, so the exam locks while Windows
has more than one active display (an extended monitor or projector). A
mirrored/duplicated projector counts as one display. Unplug or set Windows to
show on one display, then use "Restore screen monitoring" on the exam page.

Background monitoring
---------------------
launch-exam.bat starts Chrome/Edge with three switches that stop the browser
from slowing down the exam tab while the student works in another window
(Jupyter, VS Code, an exam site). If an exam browser window is already open
without them, the launcher asks the student to close it first.

Only a confirmed live sitting enables collection. Native observations include
DNS query hostnames, window titles/processes, removable drives, selected chat/
remote-control process names and clipboard text length. Clipboard text itself
is never transmitted. Screenshots require a server request tied to an event.
Paused mode stops new collection/captures. Permitted mode logs information and
does not request new screenshots. Submit/end/deadline stops collection when the
agent receives it; pre-close evidence can still be delivered afterward.

Intermittent LAN connection
--------------------------
No internet service is required. The agent bypasses the system web proxy and
refuses public-address origins or redirects. While a previously confirmed live
sitting loses its teacher LAN connection, it saves observations locally using
the last confirmed mode until that sitting's cached deadline. It does not take
new offline screenshots. It cannot receive a teacher pause/end while the LAN is
disconnected; those commands apply when it reconnects. The server discards any
observations after the actual attempt cutoff.

Events have stable IDs, original server-adjusted UTC times, HMAC signatures and
acknowledged delivery. Retries do not create duplicate records. Screenshots are
fully signed including image data and request/event identity. Queues are kept
separately for each sitting, teacher origin and lab-key fingerprint; old evidence
is never sent as part of a new exam or a different classroom configuration.

Storage is finite: up to 2000 queued observations and 8 cached requested images
per sitting, plus up to 8 quarantined images rejected permanently by the server.
Rejected images cannot block newer requests. Overflow is recorded in local diagnostics. Historical sitting
folders expire after 7 days or when the 20-folder / approximately 200 MB budget
requires cleanup. Keep the teacher server available and check queue/dropped
counts rather than treating this as unlimited evidence storage.

Diagnostics and removal
-----------------------
Run SELFTEST.bat as the student account. It checks the required Chrome/Edge
executable, interactive desktop/native capture,
TCP/ping/auth without a proxy, DNS access/schema/policies, startup configuration,
and a fresh heartbeat in the same Windows user/session. The test frame is held
only in memory and discarded. It changes no local settings or files; its signed
authentication test does not change server state. Failed checks return a nonzero
exit code. A zero exit code certifies only those native/launcher checks. Actual
browser screen-capture support, permissions, full-monitor selection and model
inference can only be confirmed in the Chrome/Edge exam page and remain
compulsory. PowerShell cannot certify them. If no DNS QueryName sample exists, make an approved local DNS lookup
and rerun the test. No website is contacted automatically for that check.

Status/logs: %LOCALAPPDATA%\SnapNPlanAgent\status.json and agent.log, plus
lease.log and screenshot-worker.log for the two helpers.
Queues: %LOCALAPPDATA%\SnapNPlanAgent\sittings\<sitting hash>\.
Do not share configuration or local evidence outside the lab.

UNINSTALL-AGENT.bat asks for administrator access and restores saved settings.
It leaves student-local logs/spools available for the lab's retention process.
Keep machine-backup.json until uninstall succeeds.

Limits
------
DNS queries are supporting evidence, not exact URLs or proof that a page was
visited. Cached lookups, unsupported resolvers and background applications affect
coverage. Three-second polling can miss short-lived window/process/USB activity.
Screen capture depends on an unlocked interactive desktop. This is an observable
exam aid, not a tamper-proof lockdown product. Run SELFTEST.bat on the student
accounts and do the practice run in README.md before the first exam.
