The operator controls the host workspace, configuration, SSH account, iPhone, Theos installation and optional IDA license. MCP clients are constrained to declared semantic tools. This is a local stdio service, with no public HTTP listener. No raw shell, unrestricted RPC, arbitrary JavaScript loader, password authentication, host-key auto-accept, or service-installation tool is exposed. An agent with separate unrestricted access to the operator's filesystem could edit approval state directly; the local CLI is a boundary for MCP clients, not a sandbox for arbitrary programs running as the operator.
Device IDs, app bundle IDs and system process name/executable pairs are explicitly
allowlisted. App discovery/enumeration filters to allowed apps. System process
discovery returns configured names and marks exact path matches; mismatched or
missing paths cannot be attached. Every system attach rediscovers the current PID
and requires one exact executable match. Frida attachments validate the observed
PID plus the injected bundle identity for apps or Process.mainModule.path for
system processes. No RPC/event access is permitted before host identity validation.
Subsequent RPCs/events recheck the corresponding allowlist, including the exact
system executable path. Detach remains available for cleanup after revocation.
Paths are compared as reported by Frida; SSH /rootfs mappings are never stripped
or treated as equivalent executable identities.
System sessions support bounded modules/symbols, selected metadata/memory reads,
native traces, logs and cleanup, all outside the UIKit main queue. Native writes,
calls, Swift/Objective-C/UI operations, spawn and restart are outside this interface.
runtime_native and app_logs accept exactly one app bundle_id or existing
session_id; stale session IDs never trigger an automatic attach. SSH uses key authentication and
the configured known_hosts file with agent/password/keyboard-interactive auth
disabled. Shell arguments are quoted from validated semantic inputs; rootless
tool paths are added explicitly to PATH.
An operation without a grant returns APPROVAL_REQUIRED with its full scope and
approval ID. The operator separately runs vesper-approve, reviews the scope,
and types approve. Only the local CLI grants requests. A grant is valid for
ten minutes, exact-argument bound, single-use and consumed atomically in SQLite.
Changing the session, artifact bytes, device or restart option requires a new request. Nothing is granted by a timeout or an unanswered prompt.
device_upload, app launch/termination, package installation, manual rollback
and uninstall require approval. Read-only device calls, local project editing
and compilation do not. Frida attach loads an inspection agent; hooks observe
calls without replacing implementation results. Theos build runs trusted local
Makefiles as the operator, so review externally modified project files.
The workflow requests deployment approval after building the package, then installs it directly. It creates no backup or rollback artifact and does not automatically uninstall or restore packages after a failed device action. Independent uninstall/rollback tools are explicit operations, not default steps.
Local file inputs are resolved within workspace/state roots. Device downloads
can create only new files in state_dir/downloads; they cannot overwrite the
approval DB, configuration, source or existing files. Remote transfers stay
within configured roots, recheck canonical paths, reject staging symlinks and
foreign owners, use a private staging directory and exclusive random temporary
files, and bound transfer sizes. Approved generic uploads check the actual
stream hash before renaming. Deployment verifies the remote package hash too.
Packages must contain exactly the expected dylib and its one-application filter plist. Maintainer scripts, global filters, symlinks, traversal and extra payloads are rejected. Package name/version/architecture and source fingerprints are checked. The approved transfer is checked internally before installation. An existing package can be replaced without a recoverable backup. A successful install command is followed directly by app restart and the requested device action; no installed-file hash, loaded-marker or crash sweep runs by default. Manual removal remains scoped to the selected deployment.
Cancellation waits for an active package installation to settle and leaves its result in place. It does not race dpkg with an automatic rollback or uninstall.
On a host/process crash, automatic actions cannot establish the device's final
state. On restart, live sessions are invalidated and unfinished deployments are
marked interrupted. server_status.recovery_required identifies those records.
Check package status and device state first. Manual tweak_rollback or
tweak_uninstall obtains a fresh approval and proceeds only if the installed
version and dylib still match the interrupted record. A partially broken dpkg
database or changed artifact requires explicit operator maintenance outside MCP;
there is no generic privileged repair shell. Inspect only the affected operation when maintenance is needed; no backup is created.
UI text is opt-in, secure text fields redact their value, metadata queries do not read object contents, and trace arguments are bounded scalars/addresses. Screenshot requests can contain visible app data and must be deliberate. The workflow explicitly captures its selected button/title and bounded nearby hierarchy as evidence. Do not select unrelated private UI.
Secret-key fields, bearer values, common credential patterns and private-key
blocks are redacted in results/events/audits. This is best-effort filtering, not
a guarantee that all sensitive free text or image pixels can be recognized.
objc_query_instances and explicit objc_inspect_object(include_values=true)
read bounded ivars. Sensitive ivar/dictionary names are checked before reading
their values; unknown objects return leased references. Only known Foundation
string/number/collection accessors are used for bounded value serialization;
arbitrary getters/descriptions and raw pointer dereferencing are not exposed.
Native/Swift layouts and concurrent object mutation can still make reads
unavailable or inconsistent; this is best-effort runtime inspection.
Audits store tool outcome and scoped approval metadata, not raw tool arguments. State files are private to the local operator. Delete/export them deliberately under the operator's data-retention policy.
Tools have execution deadlines. Process output, file sizes, object IDs, hooks, sessions, worker slots, jobs, events and UI traversals have caps. Event cursors include loss counts. Native object references are retained for identifier safety, reference-counted across expiring snapshot/operation leases, and released after their final lease ends or on detach. Active batched operations hold their input references across waits; RPCs, hooks and workflows protect sessions from idle reclamation. Retaining can delay app object deallocation. An abrupt host death may prevent release until the target process exits. Main-thread inspections and heap scans can briefly pause the app. These tools are debugging instrumentation and should be used on an isolated test device.
Crash logs are read only for a relevant failure, not as a routine post-install check. Queries inspect app-matching filenames and timestamps in the configured crash roots. Delayed report creation and inaccessible roots can limit results.
Static/runtime mapping requires matching Mach-O UUID and architecture, an observed module boundary, canonicalized IMP and compatible segment range. A database is correlated only when its input hash matches the accompanying binary. Address correlation is evidence of image identity and location, not proof of source-level behavior, especially for stripped or optimized code.