Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
92edd8e
feat(terminal): restore bounded recent command output per pane
galact-byte Sep 21, 2026
d3f3962
merge: integrate upstream main for recent output restore
galact-byte Sep 21, 2026
aa93047
docs(recent-output): fix decision note validation and refresh evidence
galact-byte Sep 21, 2026
ec9fba4
fix(terminal): confirm recent output submissions on all platforms
galact-byte Sep 21, 2026
19e72aa
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 21, 2026
997e05f
fix(cli): sync Windows completions on output restore branch
galact-byte Sep 21, 2026
ae3a43d
Merge upstream main into PR #235 and resolve conflicts
galact-byte Sep 21, 2026
ad812bb
test: fix Unix fixture collision and macOS path selection
galact-byte Sep 21, 2026
2cd35c2
Merge upstream main into PR #235, retain recent output restore
galact-byte Sep 23, 2026
49a6942
test: initialize output refs in workspace recovery fixture
galact-byte Sep 23, 2026
761dfac
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 23, 2026
e6c2260
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 23, 2026
1e23fe0
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 24, 2026
5cfdfec
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 24, 2026
0d07b1f
feat: narrow recent output restore to snapshot and storage foundation
galact-byte Sep 26, 2026
5917c5f
ci: rerun checks for recent output foundation
galact-byte Sep 26, 2026
c454ae9
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 27, 2026
086ac80
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 28, 2026
2f9ae61
fix: bound snapshot decoding and sanitize orphan wide-char flags
galact-byte Sep 28, 2026
a02ca89
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 28, 2026
9d788bc
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 28, 2026
27d37d2
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 29, 2026
f57d6be
Merge branch 'main' into feat/recent-output-restore
galact-byte Sep 30, 2026
4e39bd3
Merge branch 'main' into feat/recent-output-restore
galact-byte Oct 1, 2026
2b42430
Merge branch 'main' into feat/recent-output-restore
galact-byte Oct 1, 2026
8f25ca1
ci: retrigger checks after windows-11-arm runner lost communication
galact-byte Oct 1, 2026
4e2563e
Merge branch 'main' into feat/recent-output-restore
galact-byte Oct 2, 2026
8c248ca
Merge branch 'main' into feat/recent-output-restore
galact-byte Oct 3, 2026
03634d4
Merge branch 'main' into feat/recent-output-restore
galact-byte Oct 5, 2026
ed4a048
Merge branch 'main' into feat/recent-output-restore
galact-byte Oct 8, 2026
fdcb768
Merge branch 'main' into feat/recent-output-restore
galact-byte Oct 11, 2026
83de83a
Merge branch 'main' into feat/recent-output-restore
galact-byte Oct 15, 2026
12151b8
Merge branch 'main' into feat/recent-output-restore
galact-byte Oct 18, 2026
00eec87
ci: retry native checks after upstream animation test failure
galact-byte Oct 18, 2026
eb59724
Merge branch 'main' into feat/recent-output-restore
galact-byte Oct 30, 2026
f1b5420
Move recent output and its snapshot tests to the current Pebrel crates
Kuddev Nov 19, 2026
6ef9949
Integrate the reviewed terminal snapshot prerequisite for output storage
Kuddev Nov 19, 2026
c2548eb
Bound pane and record decoding in local output archives
Kuddev Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# 静态输出快照与本机引用的持久化边界

## Status

供审核的持久化基础;尚未接入命令采集、设置控件或窗口输出恢复。
关联 #160,本阶段不代表完整功能已交付。

## Context

终端显示、输出文件和布局会话的生命周期不同。多个 pane 可以处于同一目录,
因此目录不能作为旧输出归属。直接回放原始 VT 会再次执行控制动作;
把输出及引用放进共享工作区格式,又会让导出携带本机历史。

## Evidence

- [显示快照与校验](../../../../pebrel_terminal/src/grid/snapshot.rs)覆盖 Unicode 重排、容量和控制数据拒绝;备用屏活动时读取主屏由第二项随采集接入。
- [有界输出存储](../../../../pebrel_app/src/recent_output/storage.rs)复用原子文件写入。
- [发布生命周期](../../../../pebrel_app/src/recent_output/storage/lifecycle.rs)的回归测试覆盖两代交接、失败重试和发布回调内失效。
- 本机会话引用(`session/local_output.rs`)随第二项的逐 pane 采集交付;本项存储测试以普通文件代替会话,只验证发布回调的提交语义。

## Decision

terminal 层仅捕获和恢复主屏的静态显示字段,恢复到历史区,不重放 VT,
不改活终端屏幕或光标。反序列化与恢复先校验结构、容量和控制数据。

app 层以独立 sidecar 保存有界记录,每 pane 最多五条,每条最多 256 KiB。
正常归档最多 16 MiB,两代原子交接最多 32 MiB;超量先裁剪旧记录再生成引用。
读取 sidecar 时,解码器逐项检查 pane 引用、每个 pane 的记录数和每条记录的编码大小。它只接收一代交接数据;重复引用会使归档无效。
精确引用只属于本机自动恢复文档,共享工作区的导入和导出不携带这些引用。

先持久化输出,再发布会话引用,发布成功前保留旧引用可读取的那一代。
发布失败恢复旧归档;成功后才能回收旧代。回调成功意味着会话已经落盘,
即使回调内代次失效,也必须报告真实的持久化结果并保留交接数据。
后续接入者负责通过同一串行边界提交新的 checkpoint;无引用 checkpoint
不能等同清除全部旧历史,显式清除使用独立操作。

## Rejected alternatives

- 回放原始 VT:会重放控制动作,无法保证只恢复显示。
- 按 cwd 匹配:同目录多 pane 无法确定归属。
- 在共享会话中嵌入输出或本机引用:扩大导出范围和载入成本。
- 发布引用前覆盖旧代:中断后旧会话可能引用已丢失的数据。
- 发布成功后仅凭代次变化返回未提交:内存结果会与实际磁盘状态矛盾。

## Consequences

存储和终端边界可各自验证,后续采集及窗口接入复用同一规则。
本阶段不会自动记录命令或恢复终端输出,也不新增用户设置。
调用方须在后台执行磁盘操作,并承担持久化完成后的生命周期收尾。

## Validation

Windows 上实际运行:存储 24 项、会话相关 105 项、启动恢复 1 项通过;
`cargo test --locked -p nebula_terminal --features serde` 的 352 项通过,
包含使用现有打包资产执行的 ConPTY 生命周期测试。
应用测试启用 `gpui-test-support`;仅关闭应用测试目标的调试符号,断言不变。
这些结果验证本阶段边界,不作为尚未接入的窗口输出恢复验收。

## Supersedes

None。

## Revisit when

需要改变容量、引用身份、原子交接协议,或允许跨设备导出输出时重新审核。
2 changes: 2 additions & 0 deletions pebrel_app/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,3 +38,5 @@
- Windows Acrylic 的动画期间透明回退与计时边界见 [`窗口状态切换`](../architecture/notes/pebrel_app/platform/2026-09-22-acrylic-window-transitions.md)。
- 登录项的启动意图与首窗静默边界见 [`登录启动`](../architecture/notes/pebrel_app/platform/startup/2026-10-10-login-launch-intent.md)。
- OSC 8 本地链接的 C1 损坏恢复、显式链接身份与后台匹配边界见 [`file_uri`](../architecture/notes/pebrel_app/file_uri/2026-11-11-c1-corrupted-osc8-file-links.md)。

- 本机命令输出归档的代次、容量与发布顺序见 [最近输出的持久化边界](../architecture/notes/pebrel_app/recent_output/2026-09-21-bounded-local-output.md)。
1 change: 1 addition & 0 deletions pebrel_app/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@ mod profile_launch;
mod prompt_suggestions;
mod provider_test;
mod proxy_test;
mod recent_output;
mod remote_dirs;
mod render_cache;
#[cfg(feature = "legacy-shell")]
Expand Down
257 changes: 257 additions & 0 deletions pebrel_app/src/recent_output.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,257 @@
//! 逐终端的有界命令显示记录;调用方只提交已确认的 shell 命令。

use pebrel_terminal::grid::snapshot::DisplaySnapshot;
use pebrel_terminal::grid::{Dimensions, Grid};
use pebrel_terminal::index::Line;
use pebrel_terminal::term::cell::{Cell, Flags};
use serde::{Deserialize, Serialize};

pub(crate) mod storage;

const MAX_RECORDS: usize = 5;
const MAX_RECORD_BYTES: usize = 256 * 1024;
const MAX_CAPTURE_CELLS: usize = 4096;

// 仅在保存边界编码,按整行缩小,避免切断 UTF-8 或宽字符。
fn capture_bounded(
grid: &Grid<Cell>,
range: std::ops::Range<Line>,
byte_budget: usize,
) -> DisplaySnapshot {
let mut low = 0;
let mut high = MAX_CAPTURE_CELLS / grid.columns();
let mut best = DisplaySnapshot::capture(grid, range.clone(), 0);
while low <= high {
let rows = low + (high - low) / 2;
let candidate = DisplaySnapshot::capture(grid, range.clone(), rows * grid.columns());
if serde_json::to_vec(&candidate).is_ok_and(|bytes| bytes.len() <= byte_budget) {
best = candidate;
low = rows + 1;
} else if rows == 0 {
break;
} else {
high = rows - 1;
}
}
best
}

#[derive(Clone, Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct CommandRecord {
#[serde(default)]
pub(crate) captured_at: u64,
prompt: DisplaySnapshot,
output: DisplaySnapshot,
}

#[derive(Default)]
pub(crate) struct RecentOutput {
records: Vec<CommandRecord>,
active_output_start: Option<usize>,
}

impl RecentOutput {
pub(crate) fn begin(&mut self, grid: &Grid<Cell>) {
let mut start = grid.cursor.point.line;
while start.0 > -(grid.history_size() as i32)
&& grid[Line(start.0 - 1)][pebrel_terminal::index::Column(grid.columns() - 1)]
.flags
.contains(Flags::WRAPLINE)
{
start.0 -= 1;
}
let end = Line(grid.cursor.point.line.0 + 1);
if self.records.len() == MAX_RECORDS {
self.records.remove(0);
}
self.records.push(CommandRecord {
captured_at: std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map_or(0, |duration| duration.as_micros().min(u64::MAX as u128) as u64),
prompt: capture_bounded(grid, start..end, MAX_RECORD_BYTES / 2),
output: DisplaySnapshot::capture(grid, end..end, 0),
});
self.active_output_start = Some(grid.scrolled_out() + grid.history_size() + end.0 as usize);
}

pub(crate) fn finish(&mut self, grid: &Grid<Cell>) {
if let Some(output) = self.capture_active(grid, false) {
if let Some(record) = self.records.last_mut() {
record.output = output;
}
}
self.active_output_start = None;
}

pub(crate) fn snapshot(&self, grid: &Grid<Cell>) -> Vec<CommandRecord> {
let mut records = self.records.clone();
if let Some(output) = self.capture_active(grid, true) {
if let Some(record) = records.last_mut() {
record.output = output;
}
}
records
}

fn capture_active(&self, grid: &Grid<Cell>, include_cursor: bool) -> Option<DisplaySnapshot> {
let absolute = self.active_output_start?;
let origin = grid.scrolled_out() + grid.history_size();
let start = (absolute as i128 - origin as i128).clamp(i32::MIN as i128, i32::MAX as i128);
let end = grid.cursor.point.line.0 + i32::from(include_cursor);
let prompt_bytes = serde_json::to_vec(&self.records.last()?.prompt).ok()?.len();
// 为字段名、标点及采集时间预留空间,确保整条记录仍在预算内。
let budget = MAX_RECORD_BYTES.saturating_sub(prompt_bytes + 64);
Some(capture_bounded(grid, Line(start as i32)..Line(end), budget))
}
pub(crate) fn try_from_records(records: Vec<CommandRecord>) -> Result<Self, &'static str> {
Self::validate_records(&records)?;
Ok(Self { records, active_output_start: None })
}

pub(crate) fn validate_records(records: &[CommandRecord]) -> Result<(), &'static str> {
if records.len() > MAX_RECORDS {
return Err("too many command records");
}
for record in records {
let bytes = serde_json::to_vec(record).map_err(|_| "invalid command record")?;
if bytes.len() > MAX_RECORD_BYTES {
return Err("command record exceeds byte budget");
}
}
Ok(())
}
pub(crate) fn restore(&self, grid: &mut Grid<Cell>) -> Result<(), &'static str> {
// 每次静态导入都插在现有历史之前,因此从最新记录的输出开始。
for record in self.records.iter().rev() {
record.output.restore_scrollback(grid)?;
record.prompt.restore_scrollback(grid)?;
}
Ok(())
}
}

#[cfg(test)]
mod tests {
use super::*;
use pebrel_terminal::event::VoidListener;
use pebrel_terminal::grid::Dimensions;
use pebrel_terminal::index::{Column, Line};
use pebrel_terminal::term::{Config, Term};
use pebrel_terminal::vte::ansi;

pub(super) struct Size;
impl Dimensions for Size {
fn total_lines(&self) -> usize {
4
}
fn screen_lines(&self) -> usize {
4
}
fn columns(&self) -> usize {
32
}
}

#[test]
fn retains_five_commands_with_output_in_order_without_reexecuting() {
let mut term = Term::new(Config::default(), &Size, VoidListener);
let mut parser: ansi::Processor = ansi::Processor::new();
let mut recent = RecentOutput::default();
for index in 0..7 {
parser.advance(&mut term, format!("C:>echo {index}").as_bytes());
recent.begin(term.grid());
parser.advance(&mut term, format!("\r\nresult{index}\r\n").as_bytes());
recent.finish(term.grid());
}
let records = recent.snapshot(term.grid());
assert_eq!(records.len(), 5);
let mut target = Term::new(Config::default(), &Size, VoidListener);
RecentOutput::try_from_records(records).unwrap().restore(target.grid_mut()).unwrap();
let text = target.bounds_to_string(
pebrel_terminal::index::Point::new(
Line(-(target.grid().history_size() as i32)),
Column(0),
),
pebrel_terminal::index::Point::new(Line(-1), Column(31)),
);
assert!(!text.contains("echo 1"));
assert!(text.contains("echo 2"));
assert!(text.contains("result6"));
assert!(text.find("result2").unwrap() < text.find("result6").unwrap());
assert_eq!(target.grid().cursor.point.line, Line(0));
assert_eq!(target.grid()[Line(0)][Column(0)].c, ' ');
}

#[test]
fn loading_rejects_excess_records_instead_of_growing_on_next_command() {
let mut term = Term::new(Config::default(), &Size, VoidListener);
let mut parser: ansi::Processor = ansi::Processor::new();
parser.advance(&mut term, b"C:>echo test");
let mut recent = RecentOutput::default();
recent.begin(term.grid());
let record = recent.snapshot(term.grid()).remove(0);
assert!(RecentOutput::try_from_records(vec![record; 6]).is_err());
}

#[test]
fn loading_rejects_oversize_records_before_restore() {
let mut term = Term::new(Config::default(), &Size, VoidListener);
let mut parser: ansi::Processor = ansi::Processor::new();
for _ in 0..200 {
parser.advance(&mut term, b"long unbounded output\r\n");
}
let snapshot = DisplaySnapshot::capture(term.grid(), Line(-200)..Line(0), 6400);
let record = CommandRecord { captured_at: 0, prompt: snapshot.clone(), output: snapshot };
assert!(serde_json::to_vec(&record).unwrap().len() > MAX_RECORD_BYTES);
assert!(RecentOutput::try_from_records(vec![record]).is_err());
}

#[test]
fn encoded_record_keeps_command_and_tail_within_256_kib() {
let mut term = Term::new(Config::default(), &Size, VoidListener);
let mut parser: ansi::Processor = ansi::Processor::new();
parser.advance(&mut term, b"C:>large-tool");
let mut recent = RecentOutput::default();
recent.begin(term.grid());
for index in 0..300 {
parser.advance(
&mut term,
format!("\r\n\x1b[38;2;123;234;245mrow{index:03} output\x1b[0m").as_bytes(),
);
}
let records = recent.snapshot(term.grid());
let encoded = serde_json::to_vec(&records[0]).unwrap();
assert!(encoded.len() <= 256 * 1024, "{} encoded bytes", encoded.len());
let mut target = Term::new(Config::default(), &Size, VoidListener);
RecentOutput::try_from_records(records).unwrap().restore(target.grid_mut()).unwrap();
let text = target.bounds_to_string(
pebrel_terminal::index::Point::new(
Line(-(target.grid().history_size() as i32)),
Column(0),
),
pebrel_terminal::index::Point::new(Line(-1), Column(31)),
);
assert!(text.contains("C:>large-tool"));
assert!(text.contains("row299 output"));
assert!(!text.contains("row000 output"));
}

#[test]
fn active_output_is_captured_and_two_restores_do_not_duplicate_records() {
let mut term = Term::new(Config::default(), &Size, VoidListener);
let mut parser: ansi::Processor = ansi::Processor::new();
parser.advance(&mut term, b"C:>tool");
let mut recent = RecentOutput::default();
recent.begin(term.grid());
parser.advance(&mut term, b"\r\npartial");
let records = recent.snapshot(term.grid());
assert_eq!(records.len(), 1);
let encoded = serde_json::to_vec(&records).unwrap();
let restored =
RecentOutput::try_from_records(serde_json::from_slice(&encoded).unwrap()).unwrap();
let empty = Term::new(Config::default(), &Size, VoidListener);
let encoded_again = serde_json::to_vec(&restored.snapshot(empty.grid())).unwrap();
assert_eq!(encoded_again, encoded);
}
}
Loading
Loading