Her Own Account

A Mac That Is Hers

Oriel runs on Pippa's home Mac, an always-on machine that is deliberately not part of Dad's fleet: no fleet deploy, mirror or backup targets it, and the family's registry knows it as Pippa's, not as a workbench. Inside it there are two macOS accounts. One is Dad's, kept only to administer the machine. The other is hers. Oriel lives entirely in the second one: its engine, its recorder, its page build, its data under <data> in that account.

Which Mac that is never appears in Oriel's code. The family's port ledger places the member, the install script reads the ledger, and the commit hook refuses a registry machine name written as a host, even inside a description string. The docs say "Pippa's home Mac" and leave the rest to the ledger, so that moving Oriel to another Mac is a ledger edit, not a hunt through prose.

Why the Account Holds the Console

A camera on macOS is not a file you can open from anywhere. Access is guarded by the system's privacy framework (TCC), and the grant belongs to a specific signed program in a specific user's login session. That has three consequences that shaped Oriel's whole layout.

The recorder must run in a GUI session. A process started from an SSH login, or a daemon outside any user session, cannot be granted the camera at all. Opening one from an SSH shell fails with "Cannot use <device>", which looks like a broken capture card and is actually TCC saying no. So her account holds the Mac's console session, and the recorder is a launchd agent loaded into that session's gui/<uid> domain, restricted to the Aqua session type.
The grant is tied to a signature. TCC remembers "this signed program may use the camera". An unsigned or ad-hoc-signed rebuild is a different program to TCC, and the grant would have to be given again after every build. The recorder is signed with the family's own code-signing identity, so the Camera grant Dad gave once, in System Settings for that account, survives every rebuild.
The grant is never bypassed. If it is missing, the recorder reports denied, the page and the health check say so, and every look refuses with that reason. Nothing tries another route to the device.

Kept-Alive Jobs and One-Shot Jobs

Two launchd jobs in that session are always kept alive: com.cwk.oriel-serve, the engine on loopback, and com.cwk.oriel-recorder, the recorder app. A phone driver job can be kept alive too, one per device whose driver runs as a service rather than on demand. Everything else Oriel starts there (an audio take for a sync test, a voice take for the watch-along recorder) is a one-shot job, and one-shot jobs on macOS hide a trap that Oriel walked straight into.

The convenient command for "run this once in the GUI session" is launchctl submit. A submitted job is KeepAlive: launchd restarts it every time it exits. A phone-pairing script started that way on 2026-11-02 had run 1,443 times by the morning. Oriel's answer is a small module that builds every one-shot job with three locks, each of which stops a relaunch on its own: KeepAlive false with LaunchOnlyOnce true, a run marker the wrapper writes before the program starts (a second start finds it and exits), and a bootout by the caller when the program is done. One kind of job deliberately goes without the run marker: a program that holds a privacy grant of its own, such as the signed audio probe and its microphone grant. It must stay launchd's own child, because the wrapper's shell would otherwise stand in its place as the process macOS asks about, so it keeps the other two locks. A test fails if launchctl submit appears anywhere in the repository.

What the Account Does Not Have

Her account is kept small on purpose, and two of its absences are worth knowing:

No brain sign-ins. No coding-agent credentials live there. When Oriel needs a model (a watcher describing a recording, a helper writing up a game run), the call goes to cwkPippa or to a watcher on another Mac, which own their sign-ins. The account that holds the camera grant holds no model credentials.
No accepted terms in Dad's name. The Python environment there is created from conda-forge only. Miniconda's default channels sit behind Anaconda's terms of service, and nobody accepts terms on Dad's behalf, so the environment file is installed with --override-channels -c conda-forge.

One more operational fact follows from the placement. Firelink, the family's registry, can restart most apps from its own Mac. It cannot restart Oriel's jobs, because they live in another Mac's GUI session. Oriel's own install scripts are re-run on the home Mac instead, and as the deploy-guard lesson will show, even they ask permission before cutting a recording.

Code

The recorder's launchd agent (trimmed excerpt, deploy/com.cwk.oriel-recorder.plist; @@HOME@@ and @@DATA_ROOT@@ are filled at install)·text

<key>AssociatedBundleIdentifiers</key>  <string>com.cwk.oriel.recorder</string>
<key>KeepAlive</key>                    <true/>
<key>Label</key>                        <string>com.cwk.oriel-recorder</string>
<key>LimitLoadToSessionType</key>       <string>Aqua</string>
<key>ProcessType</key>                  <string>Interactive</string>
<key>ProgramArguments</key>
<array>
  <string>@@HOME@@/Applications/OrielRecorder.app/Contents/MacOS/OrielRecorder</string>
  <string>--root</string>
  <string>@@DATA_ROOT@@/oriel-db/recorder</string>
</array>
<key>ThrottleInterval</key>             <integer>10</integer>

Why one-shot jobs need three locks (trimmed excerpt, backend/oneshot.py)·python

"""One-shot launchd jobs that cannot run twice.

On 2026-11-02 a one-shot job loaded with ``launchctl submit`` relaunched
1,443 times overnight: a submitted job is KeepAlive, so launchd restarts it
every time it exits. ... three locks that each stop a relaunch on their own:

- ``KeepAlive`` false and ``LaunchOnlyOnce`` true: launchd itself never
  starts it again;
- a run marker: the wrapper writes it before the program starts, and a
  second start finds it, boots its own job out and exits 0;
- the caller boots the job out when the program is done (``finish``).

``launchctl submit`` is never used in this repository
(``tests/test_oneshot.py`` holds that).
"""

LAUNCHCTL_TIMEOUT_S = 15.0


def launchctl(argv, run=subprocess.run):
    """``launchctl`` with a time limit; a hang answers as a failure, never a wait."""
    command = ["/bin/launchctl", *argv]
    try:
        return run(command, capture_output=True, text=True, check=False,
                   timeout=LAUNCHCTL_TIMEOUT_S)
    except subprocess.TimeoutExpired:
        return subprocess.CompletedProcess(
            command, -1, "", f"launchctl {argv[0]} did not answer within "
                             f"{LAUNCHCTL_TIMEOUT_S:g} s")

See which domain a job lives in and whether it is kept alive (run as the account that owns it)·bash

# List this account's GUI-session jobs that belong to one app
launchctl print "gui/$(id -u)" | grep -i oriel

# Inspect one job: its state, how often it ran, and its keepalive policy
launchctl print "gui/$(id -u)/com.cwk.oriel-recorder" | grep -E 'state|runs|keepalive'

Exercise

On a Mac you control, list the launchd jobs in your own GUI domain with launchctl print gui/$(id -u). Find one job that is meant to run once (an updater, a helper) and read its keepalive and run count. Then write down, for one camera or microphone app you use, which signed program holds the grant in System Settings, Privacy & Security.

Hint

A job whose run count keeps climbing while you expected one run is the 1,443 bug in miniature. In System Settings the grant is listed by app name; codesign -dv /path/to/App.app shows the signing identity TCC remembers.