Pane secret and OSC 7577 resume commands #36
Labels
No labels
needs-info
needs-triage
ready-for-agent
ready-for-human
wayfinder:map
wayfinder:task
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Depends on
#35 Restore windows, tabs and panes after a restart
jeff/harrier
Reference
jeff/harrier#36
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Implement the Program Resume Protocol (OSC 7577, Rex revision 0.2 of 2026-11-19, which renamed the nonce to a token and added an overview and a threat model). With it, a program in a pane can tell harrier how to bring it back, and harrier runs that Resume command when the pane is restored. Blocked by the Restore issue.
The protocol's token is harrier's Pane secret. ADR 0007 records why it is passed in the environment, not through a private mount or a file.
Pane secret
PROGRAM_RESUME_TOKENin the environment of a program started on a Pty, and nowhere else.[A-Za-z0-9_-]. Never derived from a counter, a time or a pid.PROGRAM_RESUME_TOKENfrom the environment it inherited before building any program's environment.resumesetting, on by default, app-wide and overridable per profile. When it is off for a pane, the variable is not set there.PROGRAM_RESUME_TOKEN, accepts no reports and resumes nothing, whateverresumesays. The spec says such a terminal SHOULD NOT accept reports without an explicit opt-in, and SHOULD NOT resume. An opt-in can come later if anyone asks.Reports
tokenfirst andpidsecond, otherwise ignored. A wrong token is ignored and has no effect. Any other failure rejects the report and removes that owner's records: malformed, a repeated key, a missing required key, a value that does not fit its key, a limit exceeded, base64 that does not decode or has the wrong padding, or decoded text that is not valid UTF-8 or holds a control character. A report is never half applied. Unknown keys are ignored unlessneednames them.?is ignored. A token outside 22–64 characters cannot match, so it is ignored.pidis[1-9][0-9]*. An emptyargvelement is an empty argument, allowed anywhere but first.argvelements are accepted.argv[0]is a bare name or an absolute path. Decoded text containing control characters is rejected./proc/<pid>/root, by device and inode), its controlling tty is this pane's pty, and its start time is stored with the record. A record is cleared when its owner exits, or when its pid comes back with a different start time, after a short grace period for logout. On Windows the check is skipped, as the spec allows./proc/<owner>/cwdwhen the report is accepted, never OSC 7. On Windows, use the pane's location.Storage
0600, as the spec requires of saved records.:terminal). Among records none of whose owners is an ancestor of another (a shell with several stopped jobs), the most recent is saved; the spec lets a terminal choose zero, one or several. On Windows, the last write wins.Running a resume command
PATH, with the arguments passed as positional parameters so no shell ever parses one:$SHELL -l -c 'exec "$@"' sh <argv…>fish -l -c 'exec $argv' <argv…>execvethe argv directly, with the profile's environment.Terms: see
GLOSSARY.md(Pane secret, Resume command, Restore).The spec's second revision renames the nonce to the token: the key is
token=and the variablePROGRAM_RESUME_TOKEN. It also adds a Record choice section (zero, one or several of records whose owners are unrelated may be resumed) and lets the terminal return to the shell or exit once a resumed program ends. The body above, ADR 0007 and the glossary now follow it.Also waiting on libghostty-vt: it has to parse OSC 7577 and hand harrier the reports, as it does for OSC 7 and OSC 9;4. The libghostty-vt harrier pins (ghostty 1.4.1-dev, branch zig-0.17-jeff) has no parser for it — nothing under src/terminal/osc names 7577. Forgejo cannot record a dependency on that repository, so this comment is the record: #36 starts once both #35 is on main and libghostty-vt reports OSC 7577.