Luxe 0.1.3: your sessions on your phone, joinable sessions, and nested AGENTS.md

- luxe remote puts the sessions on your computer in reach of your own phone or tablet over
  Tailscale: write, steer, answer prompts, send photos, browse files, diffs and GitHub, with a
  paired device and your own Tailscale login.
- luxe join lets another program on the same machine join a running session over the RPC protocol.
- An AGENTS.md in a subfolder reaches the model the first time it works there.
- Long sessions stay fast: no stall before each model call, lighter memory, cheaper drawing.
- A session is open in one Luxe at a time, web_search shares results across its phrasings, and a
  grep glob starting with ! excludes.

The CHANGELOG has the full list.
This commit is contained in:
Evan Whittaker
2026-10-20 02:40:13 -05:00
parent 99e30d6d0f
commit d2129a886f
423 changed files with 31666 additions and 1669 deletions

View File

@@ -197,6 +197,46 @@ pub fn chapter_needs_review(budget: &ReviewBudget, chapter: &ReviewChapter) -> b
budget.chapter(&chapter.id).needs_review > 0
}
/// The one reason every item in `chapter` is accounted for: `None` when anything in it needs the
/// reviewer, or when different things vouch for different items.
pub fn shared_reason(budget: &ReviewBudget, chapter: &ReviewChapter) -> Option<Accounted> {
let mut reason: Option<Accounted> = None;
for item in &chapter.items {
let ItemVerdict::Accounted(accounted) = budget.verdict(item) else {
return None;
};
match &reason {
Some(seen) if *seen != accounted => return None,
_ => reason = Some(accounted),
}
}
reason
}
/// What one chapter asks of the reader, for a front end that has the chapters but not the lines
/// the budget is decided from.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct ChapterReading {
/// The chapter it's about
pub chapter_id: ChapterId,
/// Items still on the reviewer's list
pub needs_review: usize,
/// The label of [`shared_reason`], when there is one
#[serde(default, skip_serializing_if = "Option::is_none")]
pub reason: Option<String>,
}
/// What every chapter of `review` asks of the reader, from the budget the terminal reads.
pub fn chapter_readings(review: &GuidedReview) -> Vec<ChapterReading> {
let budget = review_budget(review, &super::review_flags(review));
let reading = |chapter: &ReviewChapter| ChapterReading {
chapter_id: chapter.id.clone(),
needs_review: budget.chapter(&chapter.id).needs_review,
reason: shared_reason(&budget, chapter).map(|reason| reason.label()),
};
review.chapters.iter().map(reading).collect()
}
fn hunk_verdict(
hunk: &ReviewHunk,
file: &ReviewFile,

View File

@@ -249,3 +249,77 @@ fn chapter_roll_up_counts_what_still_needs_review() {
assert!(chapter_needs_review(&budget, chapter));
assert_eq!(budget.chapter(&chapter.id).needs_review, 1);
}
/// The churn review as one chapter holding all three hunks, so a reason has to be shared to stand.
fn one_churn_chapter() -> GuidedReview {
let mut review = churn_review();
let mut chapter = review.chapters[0].clone();
chapter.items = review.chapters.iter().flat_map(|it| it.items.clone()).collect();
review.chapters = vec![chapter];
review
}
/// One reason behind every item is the chapter's reason.
///
/// The break this catches: a chapter that reads as needing nothing but never says why, which is
/// the line a reader checks before skipping it.
#[test]
fn a_reason_every_item_shares_is_the_chapters_reason() {
let review = one_churn_chapter();
let budget = review_budget(&review, &[]);
let reason = shared_reason(&budget, &review.chapters[0]);
assert_eq!(reason, Some(Accounted::Noise { class: NoiseKind::FormattingOnly }));
}
/// Different reasons for different items name none of them.
///
/// The break this catches: the first item's reason standing for the whole chapter, which calls a
/// lockfile change formatting.
#[test]
fn mixed_reasons_name_none() {
let mut review = one_churn_chapter();
review.files[1].hunks[0].noise = NoiseKind::Lockfile;
let budget = review_budget(&review, &[]);
assert_eq!(shared_reason(&budget, &review.chapters[0]), None);
}
/// One item on the reading list means the chapter has no reason to be skipped.
///
/// The break this catches: skipping the item that needs review when its neighbors are churn,
/// which is exactly the hunk a reviewer is there for.
#[test]
fn an_item_that_needs_review_leaves_no_reason() {
let review = one_churn_chapter();
let flagged = signal(None, Some(review.files[1].hunks[0].id.clone()), false);
let budget = review_budget(&review, &[flagged]);
assert_eq!(shared_reason(&budget, &review.chapters[0]), None);
}
/// A chapter's reading carries its id, what still needs review, and the shared reason's words.
///
/// The break this catches: a reading that reaches a phone without the count or the words, so it
/// shows every chapter as one to read, or none.
#[test]
fn readings_carry_the_count_and_the_reasons_words() {
let churn = one_churn_chapter();
let [quiet] = chapter_readings(&churn).try_into().expect("one chapter");
assert_eq!(quiet.chapter_id, churn.chapters[0].id);
assert_eq!((quiet.needs_review, quiet.reason.as_deref()), (0, Some("formatting only")));
let [unvouched] = chapter_readings(&review()).try_into().expect("one chapter");
assert_eq!((unvouched.needs_review, unvouched.reason), (1, None));
}
/// A reading weighs what the lines say, as the terminal's budget does.
///
/// The break this catches: readings decided without the line flags, which would tell a phone that
/// a chapter adding a credential is only formatting.
#[test]
fn readings_weigh_what_the_lines_say() {
let mut review = one_churn_chapter();
// Built here so no key-shaped literal sits in the source for the scanners to trip on
let key = format!("AKIA{}", "Q7ZK4M2TPLX9WRB6");
let added = review.files[1].hunks[0].lines.iter_mut().find(|line| line.new_line.is_some());
added.expect("an added line").text = format!("let key = \"{key}\";");
let [flagged] = chapter_readings(&review).try_into().expect("one chapter");
assert_eq!((flagged.needs_review, flagged.reason), (1, None));
}

View File

@@ -116,13 +116,7 @@ impl LocalGit {
let snapshot = self
.capture_turn_snapshot(TurnBaselineId::from_session_turn(session_id, turn_id), policy)
.await?;
let artifact = snapshot.artifact;
let to_persist = artifact.clone();
let project_root = self.repo_path.clone();
tokio::task::spawn_blocking(move || to_persist.persist(&project_root))
.await
.map_err(|_| GuidedReviewError::TurnBaselinePersistenceTask)??;
Ok(artifact)
self.persist_turn_snapshot(snapshot.artifact).await
}
/// Captures and retains the complete workspace immediately after a turn without changing Git state.
@@ -138,13 +132,21 @@ impl LocalGit {
policy,
)
.await?;
let artifact = snapshot.artifact;
let to_persist = artifact.clone();
self.persist_turn_snapshot(snapshot.artifact).await
}
/// Writes a snapshot off the runtime and hands it back. Moved rather than cloned, since a
/// snapshot holds every file in the workspace and a copy doubled what a turn held at once.
async fn persist_turn_snapshot(
&self,
artifact: TurnBaselineArtifact,
) -> Result<TurnBaselineArtifact, GuidedReviewError> {
let project_root = self.repo_path.clone();
tokio::task::spawn_blocking(move || to_persist.persist(&project_root))
.await
.map_err(|_| GuidedReviewError::TurnBaselinePersistenceTask)??;
Ok(artifact)
let persisted =
tokio::task::spawn_blocking(move || artifact.persist(&project_root).map(|_| artifact))
.await
.map_err(|_| GuidedReviewError::TurnBaselinePersistenceTask)??;
Ok(persisted)
}
}

View File

@@ -303,9 +303,10 @@ impl TurnBaselineArtifact {
})
};
}
let earlier = retention::newest_payload_dir(&root);
let staging = root.join(format!(".staging-{}", Uuid::new_v4()));
create_private_dir(&staging)?;
let result = self.write_staging(&staging).and_then(|()| {
let result = self.write_staging(&staging, earlier.as_deref()).and_then(|()| {
fs::rename(&staging, &target).map_err(|source| TurnBaselineStoreError::Io {
operation: "commit",
path: target.clone(),
@@ -403,7 +404,11 @@ impl TurnBaselineArtifact {
Ok(())
}
fn write_staging(&self, staging: &Path) -> Result<(), TurnBaselineStoreError> {
fn write_staging(
&self,
staging: &Path,
earlier: Option<&Path>,
) -> Result<(), TurnBaselineStoreError> {
let payload_dir = staging.join(TURN_BASELINE_PAYLOAD_DIR);
create_private_dir(&payload_dir)?;
for (path, bytes) in &self.payloads {
@@ -421,9 +426,9 @@ impl TurnBaselineArtifact {
reason: "payload metadata differs",
});
}
let payload_path = payload_dir.join(digest);
let payload_path = payload_dir.join(&digest);
if !payload_path.exists() {
write_private_file(&payload_path, bytes)?;
retention::place_payload(&payload_path, earlier, &digest, bytes)?;
}
}
let manifest = serde_json::to_vec(&self.manifest)?;
@@ -486,5 +491,8 @@ fn is_sha256_hex(value: &str) -> bool {
value.len() == 64 && value.bytes().all(|byte| byte.is_ascii_hexdigit())
}
mod retention;
pub(crate) use retention::{prune_turn_baselines, UNREFERENCED_BASELINE_AGE};
#[cfg(test)]
mod tests;

View File

@@ -0,0 +1,101 @@
//! Retention — what a new turn baseline shares with the last one, and which old ones go.
//!
//! Every agent turn captures the whole workspace twice, and few files change between turns, so a
//! baseline hard-links each payload the newest earlier one already holds instead of writing and
//! syncing it again. Only the last turn's pair is ever read back, so the rest are deleted once
//! they're an hour old; the hour spares a turn that another session in this project is still in.
use super::{TurnBaselineId, TURN_BASELINE_CACHE_RELATIVE_DIR, TURN_BASELINE_PAYLOAD_DIR};
use crate::guided_review::{source_store::write_private_file, SourceStoreError};
use std::{
collections::HashSet,
fs,
path::{Path, PathBuf},
time::{Duration, SystemTime},
};
use tracing::{debug, warn};
/// How old a baseline the last-turn record doesn't name must be before pruning deletes it.
pub(crate) const UNREFERENCED_BASELINE_AGE: Duration = Duration::from_secs(60 * 60);
/// The payload directory of the newest committed baseline under `root`, to link unchanged files
/// from; none when there isn't one yet.
pub(super) fn newest_payload_dir(root: &Path) -> Option<PathBuf> {
fs::read_dir(root)
.ok()?
.filter_map(Result::ok)
.filter(|entry| entry.file_type().is_ok_and(|kind| kind.is_dir()))
.filter(|entry| !entry.file_name().to_string_lossy().starts_with('.'))
.filter_map(|entry| Some((entry.metadata().ok()?.modified().ok()?, entry.path())))
.max_by_key(|(modified, _)| *modified)
.map(|(_, path)| path.join(TURN_BASELINE_PAYLOAD_DIR))
}
/// Puts one payload at `destination`: a hard link to `earlier`'s copy of the same digest when it
/// has a plain file of the right size, else a fresh synced write. A link that fails (another
/// filesystem, one that has none) falls back to the write.
pub(super) fn place_payload(
destination: &Path,
earlier: Option<&Path>,
digest: &str,
bytes: &[u8],
) -> Result<(), SourceStoreError> {
if let Some(source) = earlier.map(|dir| dir.join(digest)) {
let same = fs::symlink_metadata(&source)
.is_ok_and(|meta| meta.is_file() && meta.len() == bytes.len() as u64);
if same && fs::hard_link(&source, destination).is_ok() {
return Ok(());
}
}
write_private_file(destination, bytes)
}
/// Deletes every baseline under the project's cache but `keep` once it's older than `age`, along
/// with staging a crashed capture left behind. A symlink is never followed, and one that can't be
/// deleted is logged and skipped, since a stale baseline costs only disk. Returns how many went.
pub(crate) fn prune_turn_baselines(
project_root: &Path,
keep: &[&TurnBaselineId],
age: Duration,
) -> usize {
let root = project_root.join(TURN_BASELINE_CACHE_RELATIVE_DIR);
let Some(entries) = baseline_entries(&root) else {
return 0;
};
let kept: HashSet<&str> = keep.iter().map(|id| id.cache_key()).collect();
let cutoff = SystemTime::now().checked_sub(age).unwrap_or(SystemTime::UNIX_EPOCH);
let pruned = entries
.filter(|entry| is_stale(entry, &kept, cutoff))
.filter(|entry| remove_baseline(&entry.path()))
.count();
debug!(pruned, "pruned turn baselines");
pruned
}
/// The cache's entries; none when it doesn't exist yet, or can't be listed, which is logged.
fn baseline_entries(root: &Path) -> Option<impl Iterator<Item = fs::DirEntry>> {
match fs::read_dir(root) {
Ok(entries) => Some(entries.filter_map(Result::ok)),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => None,
Err(error) => {
warn!(path = %root.display(), %error, "could not list turn baselines to prune");
None
}
}
}
/// A directory, not a symlink, that `kept` doesn't name and that was last written before `cutoff`.
fn is_stale(entry: &fs::DirEntry, kept: &HashSet<&str>, cutoff: SystemTime) -> bool {
entry.file_type().is_ok_and(|kind| kind.is_dir())
&& !kept.contains(entry.file_name().to_string_lossy().as_ref())
&& entry.metadata().and_then(|meta| meta.modified()).is_ok_and(|at| at < cutoff)
}
fn remove_baseline(path: &Path) -> bool {
fs::remove_dir_all(path)
.inspect_err(|error| warn!(path = %path.display(), %error, "could not prune turn baseline"))
.is_ok()
}
#[cfg(test)]
mod tests;

View File

@@ -0,0 +1,145 @@
use super::*;
use crate::guided_review::{ReviewBase, TurnBaselineArtifact};
fn baseline(turn: &str, files: &[(&str, &[u8])]) -> TurnBaselineArtifact {
let files = files.iter().map(|(path, bytes)| (PathBuf::from(path), bytes.to_vec())).collect();
let id = TurnBaselineId::from_session_turn("session", turn);
TurnBaselineArtifact::capture(id, ReviewBase::EmptyTree, 1, false, false, 0, files)
.expect("a fixture of normal paths is a valid baseline")
}
/// Where `artifact`'s copy of `bytes` sits once persisted under `project`.
#[cfg(unix)]
fn payload(project: &Path, artifact: &TurnBaselineArtifact, bytes: &[u8]) -> PathBuf {
let digest = super::super::payload_digest(bytes);
let root = project.join(TURN_BASELINE_CACHE_RELATIVE_DIR);
root.join(artifact.manifest.id.cache_key()).join(TURN_BASELINE_PAYLOAD_DIR).join(digest)
}
fn persisted(project: &Path, turn: &str, files: &[(&str, &[u8])]) -> TurnBaselineArtifact {
let artifact = baseline(turn, files);
artifact.persist(project).expect("a valid baseline persists");
artifact
}
fn baseline_dirs(project: &Path) -> Vec<String> {
let root = project.join(TURN_BASELINE_CACHE_RELATIVE_DIR);
let mut names: Vec<String> = fs::read_dir(root)
.expect("the cache exists")
.map(|entry| entry.expect("listable").file_name().to_string_lossy().into_owned())
.collect();
names.sort();
names
}
#[cfg(unix)]
fn inode(path: &Path) -> u64 {
std::os::unix::fs::MetadataExt::ino(&fs::symlink_metadata(path).expect("the payload exists"))
}
// The break this catches: every capture writing and syncing every file again, which cost a
// project of 4,000 files about ten seconds a turn and a full copy of it on disk each time
#[cfg(unix)]
#[test]
fn a_baseline_links_a_file_the_last_one_already_holds() {
let project = tempfile::tempdir().expect("a temporary project");
let first = persisted(project.path(), "1", &[("src/main.rs", b"fn main() {}\n")]);
let second_files: &[(&str, &[u8])] = &[("src/main.rs", b"fn main() {}\n"), ("new.rs", b"new")];
let second = persisted(project.path(), "2", second_files);
let main = b"fn main() {}\n".as_slice();
assert_eq!(
inode(&payload(project.path(), &first, main)),
inode(&payload(project.path(), &second, main))
);
let loaded = TurnBaselineArtifact::load(project.path(), &second.manifest.id);
assert_eq!(loaded.expect("the linked baseline loads"), second);
}
// The break this catches: linking whatever file sits under the digest's name, so a truncated
// copy carries into every later baseline and none of them load
#[cfg(unix)]
#[test]
fn an_earlier_copy_of_the_wrong_size_is_written_fresh() {
let project = tempfile::tempdir().expect("a temporary project");
let first = persisted(project.path(), "1", &[("a.rs", b"whole")]);
let first_copy = payload(project.path(), &first, b"whole");
fs::write(&first_copy, b"cut").expect("the fixture truncates the earlier copy");
let second = persisted(project.path(), "2", &[("a.rs", b"whole")]);
assert_ne!(inode(&first_copy), inode(&payload(project.path(), &second, b"whole")));
assert!(TurnBaselineArtifact::load(project.path(), &second.manifest.id).is_ok());
}
// The break this catches: linking a symlink planted under the digest's name, which hard-links
// the symlink itself into the new baseline. Its target is as long as the payload, since a
// symlink's own size is its target's length, so the size check alone can't turn it away
#[cfg(unix)]
#[test]
fn an_earlier_copy_that_is_a_symlink_is_written_fresh() {
let project = tempfile::tempdir().expect("a temporary project");
let first = persisted(project.path(), "1", &[("a.rs", b"whole")]);
let first_copy = payload(project.path(), &first, b"whole");
fs::remove_file(&first_copy).expect("the fixture replaces the earlier copy");
std::os::unix::fs::symlink("abcde", &first_copy).expect("the fixture plants a symlink");
let second = persisted(project.path(), "2", &[("a.rs", b"whole")]);
let second_copy = fs::symlink_metadata(payload(project.path(), &second, b"whole"));
assert!(second_copy.expect("the payload exists").is_file());
}
// The break this catches: linking from the oldest baseline rather than the newest, which holds
// least of what the workspace has now
#[cfg(unix)]
#[test]
fn links_come_from_the_newest_baseline() {
let project = tempfile::tempdir().expect("a temporary project");
let older = persisted(project.path(), "1", &[("a.rs", b"a")]);
let newer = persisted(project.path(), "2", &[("a.rs", b"b")]);
let root = project.path().join(TURN_BASELINE_CACHE_RELATIVE_DIR);
let older_dir = root.join(older.manifest.id.cache_key());
let hours_ago = SystemTime::now() - Duration::from_secs(2 * 60 * 60);
fs::File::open(&older_dir).and_then(|dir| dir.set_modified(hours_ago)).expect("backdated");
let newest = newest_payload_dir(&root).expect("there are baselines");
assert_eq!(newest, root.join(newer.manifest.id.cache_key()).join(TURN_BASELINE_PAYLOAD_DIR));
}
// The break this catches: pruning that ignores what the last-turn record names, losing the one
// review the cache exists for, or that deletes nothing at all
#[test]
fn pruning_deletes_old_baselines_but_the_ones_kept() {
let project = tempfile::tempdir().expect("a temporary project");
let before = persisted(project.path(), "1", &[("a.rs", b"a")]);
let after = persisted(project.path(), "2", &[("a.rs", b"b")]);
persisted(project.path(), "3", &[("a.rs", b"c")]);
let keep = [&before.manifest.id, &after.manifest.id];
assert_eq!(prune_turn_baselines(project.path(), &keep, Duration::ZERO), 1);
let mut kept = vec![before.manifest.id.cache_key(), after.manifest.id.cache_key()];
kept.sort();
assert_eq!(baseline_dirs(project.path()), kept);
}
// The break this catches: pruning by the record alone, which deletes the baseline of a turn
// another session in the project is still running
#[test]
fn pruning_spares_a_baseline_younger_than_the_age() {
let project = tempfile::tempdir().expect("a temporary project");
persisted(project.path(), "1", &[("a.rs", b"a")]);
assert_eq!(prune_turn_baselines(project.path(), &[], UNREFERENCED_BASELINE_AGE), 0);
assert_eq!(baseline_dirs(project.path()).len(), 1);
}
// The break this catches: staging a crashed capture left behind piling up forever, since no
// record ever names it
#[test]
fn pruning_deletes_abandoned_staging() {
let project = tempfile::tempdir().expect("a temporary project");
let staging = project.path().join(TURN_BASELINE_CACHE_RELATIVE_DIR).join(".staging-crashed");
fs::create_dir_all(staging.join(TURN_BASELINE_PAYLOAD_DIR)).expect("the fixture stages");
assert_eq!(prune_turn_baselines(project.path(), &[], Duration::ZERO), 1);
assert!(!staging.exists());
}
// The break this catches: a project that has never captured a baseline failing its first turn
#[test]
fn pruning_a_project_with_no_cache_does_nothing() {
let project = tempfile::tempdir().expect("a temporary project");
assert_eq!(prune_turn_baselines(project.path(), &[], Duration::ZERO), 0);
}