Measure, Don't Narrate

"A correct observation and a plausible premise produce the same outcome, so the outcome never disagrees with you."

The Restart That Never Happened

Tearing down a scratch engine, a session ran pkill -f backend.serve, then saw -15 beside the real engine's label in launchctl list, read it as the SIGTERM it had just sent, confirmed the port still answered, and reported that it had killed the owner's engine and launchd had restarted it. It wrote that into the repository's gotchas and a shared learning as a lesson paid for. None of it happened. The engine ran under a different command line, so the pattern matched nothing, and pkill with no match prints nothing. The second column of launchctl list is the last exit status, from whenever. A port that answers is equally true whether or not anything restarted. The one cheap observation that would have settled it, the process start time, showed a start two days earlier. A fabricated incident in a gotcha list is worse than no entry, because it sounds paid for and the next reader inherits a false model.

Old Processes Serve Old Code

The same observation explains a whole family of silent half-failures. A service under launchd imports its code once, at startup. A workshop engine kept briefing work against a registry fixed seven hours earlier; another app's rebuilt web client asked a stale engine for response fields it did not send, and quietly did nothing. Two numbers settle it: the serving process's start time and the time of the newest commit to the code it should be running. If the process is older, it is the process, not the code. Measured again while this lesson was being written: a workshop engine on this Mac had started half an hour before a commit to its own registry.

Correct Behaviour, Wrong Reason

The most durable wrong claims are the ones whose outcome is right. A kit comment said Bundle.main.resourceURL is nil for a SwiftPM executable, which is why an unpackaged run served a placeholder page. The placeholder really appeared, but the property is the build directory, not nil; the page appeared because the expected subfolder was missing. A watch module documented one dictation screen as "the only in-app way" to change language, because that screen worked; on the owner's wrist the switch turned out to be a swipe up on the ordinary screen. A claim that something is the only way is a claim about the whole platform, and getting one way to work cannot establish it. And a note that "new files in a path dependency are never picked up" was retracted by its own author after a five-minute probe picked one up; what was established was that a consumer's build can go stale, and that comparing the module's timestamp with the new file's settles it.

This quest was held to the same standard. Two claims in the family's own notes did not survive being measured for these lessons: that the hardened runtime changes a certificate-signed app's designated requirement, and that an ssh session can never launch a GUI app. The lessons say what the measurements showed.

Code

who.sh: which process answers this port, since when, and is it older than its code?·bash

#!/bin/zsh
# Which process is really answering on this port, since when, and is it older than the code it should run?
set -euo pipefail
port=${1:?port} code_path=${2:?path whose last commit the server must include}

pid=$(/usr/sbin/lsof -nP -iTCP:"$port" -sTCP:LISTEN -t | head -1)
[[ -n "$pid" ]] || { print "nothing listens on :$port"; exit 1; }
started=$(ps -o lstart= -p "$pid" | sed "s/ *$//")
command=$(ps -o command= -p "$pid" | cut -c1-80)
started_epoch=$(date -j -f '%a %b %d %T %Y' "$started" +%s)
commit_epoch=$(git log -1 --format=%ct -- "$code_path")

print "pid $pid on :$port, started $started"
print "command: $command"
print "last commit touching $code_path: $(git log -1 --format='%h %ci' -- "$code_path")"
if (( started_epoch < commit_epoch )); then
  print "STALE: the process predates that commit, so it is not running that code"
else
  print "fresh: the process started after that commit"
fi

Three readings, and what each can and cannot tell you·text

Run while this lesson was written, against a workshop engine on the same Mac (its label generalized):

  pid 70332 on :9500, started Mon Sep 14 21:38:18 2026
  last commit touching the registry: 2026-09-14 22:07:25
  STALE: the process predates that commit, so it is not running that code

  $ launchctl list | grep workshop
  70332   -15   com.example.workshop-serve   <- -15 is the LAST exit status, from some earlier
                                                stop. It says nothing about now.

  $ pkill -f 'a-pattern-that-matches-nothing'; echo $?
  1                                          <- no output at all; "|| true" makes it look done

Exercise

Run who.sh against a service on your Mac and a path in its repository, and record whether it is fresh. Then prove the two instruments that lie: run pkill -f with a pattern that matches nothing and record its output and exit status, and find a job in launchctl list with a non-zero second column and use ps -o lstart= to show it has not exited recently. Finally, pick one comment in your own code that claims something is "the only way" or "never happens", and either measure it or rewrite it as what was actually observed.

Hint

lsof -t prints only process ids, which makes it safe to use in a variable. For a stopped job, launchctl print gui/$(id -u)/<label> shows the state and the last exit reason in words, which is a better reading than the list's column.