Module file_ops 

Block-file append/persist helpers and global-transcript mirroring.

Enums

ExistingFileStat 🔒

Append data to a block’s terminal output file, publish a MPS event, and write-through to FileStore (if provided).

Functions

append_output_line

Appends one NDJSON stdout line, plus the newline the frontend’s line splitter needs, to the block’s output file and global_output_zone.

append_transcript 🔒

The agent-transcript half of handle_append_block_file (Phase 5a-3, SPEC_AGENT_PANE_BOUNDED_LIVE_WINDOW_MIGRATION_2026_09_23.md §6.3.7 item 5).

append_transcript_lines 🔒

append_lines on a transcript file, creating it on first write (or if another instance deleted it since). Whole non-blank lines only: a torn last line is closed, not continued (filestore/counter.rs). With stamp, the output.tsidx receive-time record is written in the same transaction (one commit, not two). Errors are logged and swallowed.

append_tsidx_entry 🔒

Append one receive-time record to a zone’s output.tsidx sidecar: NDJSON {"off":<byte offset the batch starts at in output>,"ms":<unix ms>}. Batch granularity is deliberate — one flush of one turn’s output; sub-batch precision has no UI meaning (SPEC_AGENT_PANE_SESSION_SCOPED_SCROLLBACK_AND_AGENT_HISTORY_VIEW_2026_08_09.md §4.4). Fire-and-forget like every other write on this path: any failure logs at debug and the transcript append is unaffected. Only called for agent transcript streams (never PTY term data).

handle_append_block_file

handle_truncate_block_file

Truncate a block’s terminal output file and publish a MPS event. Port of Go’s HandleTruncateBlockFile.

mirror_append_to_global 🔒

Append data to the global transcript zone’s output file, creating it lazily on first write, and return where it landed. Mirrors the per-channel write-through in handle_append_block_file; all errors are logged and swallowed (None) so the hot stdout path is never blocked by the global store.

persist_user_line

Persist a user message the controller wrote to the agent’s stdin, so parseHistoryLines can reconstruct its user_message node on reopen.

publish_transcript_changed

Tell a block’s panes that its transcript output was replaced or deleted as a whole (Phase 5a-3), so an open pane resyncs at once instead of on its next read. fileop is mps::FILE_OP_REPLACE — with the new generation and line count read from filestore — or mps::FILE_OP_DELETE. Call it, with the replace or delete itself, inside with_transcript_order.

resolve_global_output_zone 🔒

Resolve a block’s GLOBAL transcript zone (agent:<defId>:current) from its agentId meta, looking the block up in mstore. Returns None for non-agent blocks, when there’s no store, or when the block can’t be loaded — the caller then passes None and no global mirror happens. Shared by the subprocess / persistent / acp agent controllers.

transcript_order_lock 🔒

Serializes one block’s transcript appends with their publish (see append_transcript). Striped rather than per block: bounded memory and nothing to clean up; two blocks that share a stripe only wait for each other’s append.

unix_ms_now 🔒

Current unix time in ms, or 0 if the clock is before the epoch (never in practice; 0 reads as “unknown” on the consumer side, same as no stamp).

with_transcript_order

Run f holding block_id’s transcript order lock — the lock every append holds from its first write to its publish (see append_transcript). A replace or delete of the block’s transcript, and its announcement (publish_transcript_changed), run inside it, so no append’s write and event can interleave with them and one block’s events stay in order (review of #3636). f must not append to the same block: the lock isn’t reentrant.