Skip to content
C.W.K.
Stream
Lesson 04 of 05 · published

Rematerialize, Never Resurrect

~12 min · restore, declaration, allowlist, boot-uuid, pid

Level 0Spark
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete

A Saved PID Is a Ghost

After a reboot, or after the daemon itself is gone, a number you wrote down is not a process. It is a ghost that might now belong to someone else, or to no one. Restore that treats a saved PID as still alive is how you attach to the wrong job, or to nothing, and then tell the operator the compiler is back. It is not back. A new process with a coincidental number is not the old process. Resurrection is the lie. Rematerialization is the truth: this is a new process launched from a saved recipe.

The recipe is a declaration. Host, command, directory, split geometry, maybe a seat name. Restore re-runs that command in that directory on that host. It does not scrape the last line of the journal and hope. An arbitrary command caught mid-flight is how you duplicate side effects — a deploy that already ran, a migration that already migrated, a rm that already removed. The journal is history of output, not a script to replay as input.

The Allowlist Is the Only Afterlife

A shell recipe is easy: launch the declared shell in the declared directory. A REPL or an editor is different. People want python back, or vim back, as itself, not as a shell that happens to have been in the middle of a file. That afterlife is allowed only for programs on an allowlist. The default list is a product decision, and operators can extend it. It is not a heuristic that sniffs argv[0] and guesses. If it is not listed, restore gives you the declared shell, not a second copy of a compiler that was halfway through a build.

Guessing is how you resurrect the dangerous half of a command. An allowlist is how you say, out loud, which foreground programs are safe to start again as themselves. Everything else comes back as the recipe's shell and waits. That wait is not a missing feature. It is the refusal to duplicate work.

Boot UUID Draws the Line

Live processes do not survive a reboot. Declarations do. The daemon needs a line it cannot argue with: this boot is not that boot. A boot UUID — sysctl kern.bootsessionuuid, not a hardware IOKit id — is that line. Same boot, daemon still up: a crashed projection can reattach to living jobs. Daemon restart on the same boot: PTYs are gone; restore rematerializes from declarations. New boot, living jobs are gone, restore rematerializes from declarations only. No amount of clever PID storage crosses that line honestly.

This is the Mac-owned root the phone will stand on. A pocket surface that "restores" by pretending last week's PID is still there is a pocket surface that will type into the wrong place. Restore tells the truth in the chrome: new process, old recipe. The operator can decide whether to run it.

Restore is a recipe, not a PID. Reboot restores declarations. Live processes die with the boot. The allowlist is the only place a REPL or editor gets to come back as itself.

Code

A declaration is a recipe; a PID is not in it·json
{
  "kind": "pane-declaration",
  "host": "local",
  "directory": "~/Projects/example",
  "command": "zsh",
  "foreground": {
    "program": "python",
    "restart": "allowlisted"
  },
  "geometry": { "rows": 40, "cols": 120, "split": "left" },
  "boot_uuid": "current-boot-or-none",
  "pid": null
}

# Restore (honest)
# Daemon crash or restart: PTYs are gone. Process identity is gone.
# Restore rematerializes declarations. It never reattaches a vanished PID.
# Remembered shells in a directory come back. SSH, workflows, and
# arbitrary commands do not auto-launch.
# Allowlisted foreground programs may restart as themselves.
# Everything else waits at the declared shell.
# Never take a command from the journal and type it.

External links

Exercise

Write two restore stories: (1) a pane that was a shell in a project directory with vim open, after a reboot; (2) a pane that was a shell in the same directory with make halfway done, after a reboot. For each, name what launches, what does not, and one sentence you would show in the chrome so nobody thinks the old PID came back.
Hint
vim can be allowlisted as itself. make cannot. If both stories launch the same thing, the allowlist is not doing its job — or restore is still scraping the journal.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.