Pane secret and OSC 7577 resume commands #36

Open
opened 2026-11-18 19:42:13 -06:00 by jeff · 2 comments
Owner

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

  • Set as PROGRAM_RESUME_TOKEN in the environment of a program started on a Pty, and nowhere else.
  • At least 128 bits from a CSPRNG, as 22 to 64 characters of [A-Za-z0-9_-]. Never derived from a counter, a time or a pid.
  • A fresh secret every time a program starts in a pane, including a pane's restored program and the profile program started after it exits. Never shared between panes.
  • Serial and Message panes get none.
  • harrier removes PROGRAM_RESUME_TOKEN from the environment it inherited before building any program's environment.
  • A resume setting, on by default, app-wide and overridable per profile. When it is off for a pane, the variable is not set there.
  • Elevated or root: a harrier running elevated on Windows, or as root on Linux, sets no PROGRAM_RESUME_TOKEN, accepts no reports and resumes nothing, whatever resume says. 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

  • Parsed strictly, exactly as the spec says: token first and pid second, 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 unless need names them. ? is ignored. A token outside 22–64 characters cannot match, so it is ignored. pid is [1-9][0-9]*. An empty argv element is an empty argument, allowed anywhere but first.
  • Limits: at least 2048 bytes in total and 64 argv elements are accepted.
  • argv[0] is a bare name or an absolute path. Decoded text containing control characters is rejected.
  • Linux pid check: the pid is alive, runs as harrier's own user, has the same root directory as harrier (/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.
  • Directory: on Linux, read /proc/<owner>/cwd when the report is accepted, never OSC 7. On Windows, use the pane's location.
  • Other sequences never touch records: a full or soft reset (RIS, DECSTR), the alternate screen, erasing the display or scrollback, and prompt marks (OSC 133) carry no token, so they leave a pane's records alone.

Storage

  • Records are kept per pane, keyed by owner pid, at most about 8.
  • A resume command is saved with the user it was accepted as. Restore discards one saved by another user, so that one user's command never runs with another's rights. The restore file is already the user's own and 0600, as the spec requires of saved records.
  • The resume command that is saved is the record whose owner is the ancestor nearest the pane's program (for example nvim rather than the claude running in nvim's :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

  • Through the profile's shell, so its startup files set PATH, with the arguments passed as positional parameters so no shell ever parses one:
    • POSIX shells (sh, bash, zsh, dash, ksh): $SHELL -l -c 'exec "$@"' sh <argv…>
    • fish: fish -l -c 'exec $argv' <argv…>
    • Anything else: execve the argv directly, with the profile's environment.
    • The shell is identified by the base name of the profile's program.
  • In the record's directory. If that is gone, in the directory a new pane of that profile would start in.
  • With default terminal modes: nothing of the old program's screen, modes or keyboard state is brought back.
  • When it exits, the pane starts its profile's program in that directory (the spec allows returning to the shell or closing), with a new pane secret. If it cannot be executed at all, the pane shows a Message, as a failed spawn does today.
  • No confirmation before running it. The spec trusts programs of the same user, and the state file is theirs to write anyway.

Terms: see GLOSSARY.md (Pane secret, Resume command, Restore).

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 - Set as `PROGRAM_RESUME_TOKEN` in the environment of a program started on a Pty, and nowhere else. - At least 128 bits from a CSPRNG, as 22 to 64 characters of `[A-Za-z0-9_-]`. Never derived from a counter, a time or a pid. - A fresh secret every time a program starts in a pane, including a pane's restored program and the profile program started after it exits. Never shared between panes. - Serial and Message panes get none. - harrier removes `PROGRAM_RESUME_TOKEN` from the environment it inherited before building any program's environment. - A `resume` setting, on by default, app-wide and overridable per profile. When it is off for a pane, the variable is not set there. - **Elevated or root**: a harrier running elevated on Windows, or as root on Linux, sets no `PROGRAM_RESUME_TOKEN`, accepts no reports and resumes nothing, whatever `resume` says. 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 - Parsed strictly, exactly as the spec says: `token` first and `pid` second, 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 unless `need` names them. `?` is ignored. A token outside 22–64 characters cannot match, so it is ignored. `pid` is `[1-9][0-9]*`. An empty `argv` element is an empty argument, allowed anywhere but first. - Limits: at least 2048 bytes in total and 64 `argv` elements are accepted. - `argv[0]` is a bare name or an absolute path. Decoded text containing control characters is rejected. - **Linux pid check**: the pid is alive, runs as harrier's own user, has the same root directory as harrier (`/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. - **Directory**: on Linux, read `/proc/<owner>/cwd` when the report is accepted, never OSC 7. On Windows, use the pane's location. - **Other sequences never touch records**: a full or soft reset (RIS, DECSTR), the alternate screen, erasing the display or scrollback, and prompt marks (OSC 133) carry no token, so they leave a pane's records alone. ## Storage - Records are kept per pane, keyed by owner pid, at most about 8. - A resume command is saved with the user it was accepted as. Restore discards one saved by another user, so that one user's command never runs with another's rights. The restore file is already the user's own and `0600`, as the spec requires of saved records. - The resume command that is saved is the record whose owner is the ancestor nearest the pane's program (for example nvim rather than the claude running in nvim's `: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 - Through the profile's shell, so its startup files set `PATH`, with the arguments passed as positional parameters so no shell ever parses one: - POSIX shells (sh, bash, zsh, dash, ksh): `$SHELL -l -c 'exec "$@"' sh <argv…>` - fish: `fish -l -c 'exec $argv' <argv…>` - Anything else: `execve` the argv directly, with the profile's environment. - The shell is identified by the base name of the profile's program. - In the record's directory. If that is gone, in the directory a new pane of that profile would start in. - With default terminal modes: nothing of the old program's screen, modes or keyboard state is brought back. - When it exits, the pane starts its profile's program in that directory (the spec allows returning to the shell or closing), with a new pane secret. If it cannot be executed at all, the pane shows a Message, as a failed spawn does today. - No confirmation before running it. The spec trusts programs of the same user, and the state file is theirs to write anyway. Terms: see `GLOSSARY.md` (Pane secret, Resume command, Restore).
Author
Owner

The spec's second revision renames the nonce to the token: the key is token= and the variable PROGRAM_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.

The spec's second revision renames the nonce to the token: the key is `token=` and the variable `PROGRAM_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.
Author
Owner

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.

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.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
jeff/harrier#36
No description provided.