Reading, sending and waiting

Three operations make up the working cycle with any process in the Terminal: read what it wrote, send what you want, and wait for it to reach a state before the next step. In the interface, all three are direct gestures — scroll, type, look. On the command line they have their own contract, and that contract is what makes automation predictable.

Read the history

In the interface, the history is the panel’s own content: scroll back to see what passed.

On the command line, reading has three modes, and choosing the right one avoids surprises:

Mode	What it returns	When to use it
Bounded page	A delimited block, with the cursor to continue from there	You want to follow along without re-reading everything
Only what is new	Only the output since a previous read	You already read up to a point and want what came after
Whole retained session	Everything still stored	You need the full context of what remains

Rules that apply to every mode:

• Without a cursor and without a limit, the read pages the retained session and returns everything that exists.
• The cursor returned by a read is what you pass to the next read to receive only the new part.
• There is a per-read ceiling and a ceiling for the whole session. When the oldest part has already been discarded, the result says so instead of pretending to be complete.
• The modes are mutually exclusive: asking for the whole session together with a line limit, or a line limit together with a cursor, is an argument error.
• The read prioritizes the live screen. If the process draws a full-screen interface (an agent, a terminal editor), the human-readable read shows that rendered screen; the raw text remains available in the structured read.
• A panel with no live session fails with a notice, instead of returning an empty read: the panel exists, but there is nothing running in it.

Send text

• The text can come directly in the call or from a file. For multi-line texts, use a file: shell quoting mangles newlines and quotes in a long text.
• Sending does not imply that Enter was pressed or that the process understood: you must ask for Enter explicitly when you want the line submitted.
• A refused send fails the command. If the response says the send was not accepted, the next step must not be treated as if it had been.
• Interrupting is different from sending. The interrupt delivers the stop signal to the process — it is the equivalent of a cancellation, and it can interrupt an agent’s work in progress.

Wait before sending

Writing to a process that is not ready yet is the most common cause of scrambled text. The wait exists for that:

• Wait for the process to exit — useful for commands that finish on their own.
• Wait for the agent’s interface to go idle — this is what you want before sending the first message to an agent that just came up.
• The wait has a time ceiling and a default; if the ceiling is too short, the wait expires even with the process alive.
• An unsatisfied condition fails the command. Chaining send and wait without checking the result masks both a refused send and an expired wait.

Recommended sequence

1. Create the session (with the agent, if that is the case).
2. Wait for the condition that says the process is ready.
3. Read what is already on screen — that is what confirms the interface took over.
4. Send the text, asking for Enter.
5. Wait again before reading the result.
6. Read only what is new, from the previous read’s cursor.

On the command line

The exact options for reading, sending, interrupting and waiting — including the ceilings and the mutually exclusive modes — are in Terminal command reference.