hakula139
diff --git a/‎.cspell/words.txt‎
Lines changed: 5 additions & 0 deletions b/‎.cspell/words.txt‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 29 additions & 17 deletions b/‎CLAUDE.md‎
Lines changed: 29 additions & 17 deletions
diff --git a/‎Cargo.lock‎
Lines changed: 13 additions & 0 deletions b/‎Cargo.lock‎
Lines changed: 13 additions & 0 deletions
diff --git a/‎Cargo.toml‎
Lines changed: 10 additions & 2 deletions b/‎Cargo.toml‎
Lines changed: 10 additions & 2 deletions
diff --git a/‎README.md‎
Lines changed: 2 additions & 0 deletions b/‎README.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎crates/oxide-code/Cargo.toml‎
Lines changed: 1 addition & 0 deletions b/‎crates/oxide-code/Cargo.toml‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎crates/oxide-code/src/client/anthropic.rs‎
Lines changed: 2 additions & 2 deletions b/‎crates/oxide-code/src/client/anthropic.rs‎
Lines changed: 2 additions & 2 deletions
diff --git a/‎crates/oxide-code/src/config/oauth.rs‎
Lines changed: 30 additions & 27 deletions b/‎crates/oxide-code/src/config/oauth.rs‎
Lines changed: 30 additions & 27 deletions
@@ -10,6 +10,7 @@ codex
 creds
 crossterm
 deserialize
+disambiguable
 dtolnay
 feff
 gitui
@@ -36,8 +37,12 @@ sysname
 SYSPROMPT
 thiserror
 throbber
+tildified
+tildify
+TOCTOU
 tokio
 tracing
+unresumable
 venv
 xxhash
 yazi
@@ -30,14 +30,22 @@ ox     # Start an interactive session
 ├── config.rs                   # Configuration loading and layered merging
 ├── config/
 │   ├── file.rs                 # TOML config file discovery, parsing, and merge (user + project)
-│   └── oauth.rs                # Claude Code OAuth credentials (macOS Keychain + file), token refresh, file locking
+│   └── oauth.rs                # Claude Code OAuth credentials (macOS Keychain + file), token refresh, directory-based advisory lock
 ├── main.rs                     # CLI entry point, agent loop, TUI / REPL / headless dispatch
 ├── message.rs                  # Conversation message types
 ├── prompt.rs                   # System prompt builder (section assembly)
 ├── prompt/
 │   ├── environment.rs          # Runtime environment detection (platform, git, date, marketing name)
 │   ├── instructions.rs         # Instruction file discovery and loading (CLAUDE.md, AGENTS.md)
 │   └── sections.rs             # Static prompt section constants (intro, guidance, style)
+├── session.rs                  # Session module root
+├── session/
+│   ├── entry.rs                # JSONL entry types (Header, Message, Title, Summary) and metadata structs
+│   ├── list_view.rs            # `ox --list` table rendering (writes to any `impl Write`)
+│   ├── manager.rs              # SessionManager: lifecycle (start, resume, record, finish)
+│   ├── path.rs                 # Filesystem-safe project subdirectory derivation (sanitize_cwd)
+│   ├── resolver.rs             # CLI `--continue` argument resolution (ResumeMode, resolve_session)
+│   └── store.rs                # SessionStore / SessionWriter: file I/O, XDG path, listing
 ├── tool.rs                     # Tool trait, registry, definitions
 ├── tool/
 │   ├── bash.rs                 # Shell command execution with timeout
@@ -47,22 +55,26 @@ ox     # Start an interactive session
 │   ├── read.rs                 # File reading with line numbers and pagination
 │   └── write.rs                # File writing with directory creation
 ├── tui.rs                      # TUI module root
-└── tui/
-    ├── app.rs                  # Root App struct, tokio::select! event loop, render dispatch
-    ├── component.rs            # Component trait and Action enum
-    ├── components.rs           # Components module root
-    ├── components/
-    │   ├── chat.rs             # Scrollable chat with markdown, tool styling, thinking display
-    │   ├── input.rs            # Multi-line input area (ratatui-textarea)
-    │   └── status.rs           # Status bar (model, spinner, status, working directory)
-    ├── event.rs                # AgentEvent, UserAction, AgentSink trait, ChannelSink, StdioSink
-    ├── markdown.rs             # Markdown module root (pulldown-cmark + syntect renderer)
-    ├── markdown/
-    │   ├── highlight.rs        # Syntax highlighting (syntect lazy-loaded SyntaxSet / ThemeSet)
-    │   └── render.rs           # pulldown-cmark event walker, inline / block / list / table rendering
-    ├── terminal.rs             # Terminal init / restore, synchronized output, panic hook
-    ├── theme.rs                # Catppuccin Mocha palette, style helpers
-    └── wrap.rs                 # Word-wrap with continuation indent for styled lines
+├── tui/
+│   ├── app.rs                  # Root App struct, tokio::select! event loop, render dispatch
+│   ├── component.rs            # Component trait and Action enum
+│   ├── components.rs           # Components module root
+│   ├── components/
+│   │   ├── chat.rs             # Scrollable chat with markdown, tool styling, thinking display
+│   │   ├── input.rs            # Multi-line input area (ratatui-textarea)
+│   │   └── status.rs           # Status bar (model, spinner, status, working directory)
+│   ├── event.rs                # AgentEvent, UserAction, AgentSink trait, ChannelSink, StdioSink
+│   ├── markdown.rs             # Markdown module root (pulldown-cmark + syntect renderer)
+│   ├── markdown/
+│   │   ├── highlight.rs        # Syntax highlighting (syntect lazy-loaded SyntaxSet / ThemeSet)
+│   │   └── render.rs           # pulldown-cmark event walker, inline / block / list / table rendering
+│   ├── terminal.rs             # Terminal init / restore, synchronized output, panic hook
+│   ├── theme.rs                # Catppuccin Mocha palette, style helpers
+│   └── wrap.rs                 # Word-wrap with continuation indent for styled lines
+├── util.rs                     # Shared utilities module root
+└── util/
+    ├── lock.rs                 # Async retry helper for advisory locks (used by oauth)
+    └── path.rs                 # Path display helpers (`tildify`: rewrite $HOME prefix as ~/)
 ```
 
 ## Coding Conventions
 
@@ -20,6 +20,7 @@ anyhow = "1"
 clap = { version = "4", features = ["derive"] }
 crossterm = { version = "0.29", features = ["event-stream"] }
 dirs = "6"
+fs4 = { version = "0.13", features = ["sync"] }
 futures = "0.3"
 globset = "0.4"
 ignore = "0.4"
@@ -44,7 +45,14 @@ syntect = { version = "5", default-features = false, features = [
   "regex-onig",
 ] }
 tempfile = "3"
-time = { version = "0.3", features = ["local-offset"] }
+time = { version = "0.3", features = [
+  "formatting",
+  "local-offset",
+  "macros",
+  "parsing",
+  "serde",
+  "serde-well-known",
+] }
 toml = "0.8"
 tokio = { version = "1", features = [
   "io-std",
@@ -63,7 +71,7 @@ tracing-subscriber = { version = "0.3", default-features = false, features = [
   "fmt",
 ] }
 unicode-width = "0.2"
-uuid = { version = "1", features = ["v4"] }
+uuid = { version = "1", features = ["serde", "v4"] }
 xxhash-rust = { version = "0.8", features = ["xxh64"] }
 
 [profile.release]
 
@@ -21,6 +21,7 @@ Early development. What works today:
 - System prompt with CLAUDE.md / AGENTS.md injection
 - Authentication (API key and Claude Code OAuth)
 - TOML config file with layered loading
+- Session persistence with JSONL conversation logs, resume, and listing
 
 See [`docs/roadmap.md`](docs/roadmap.md) for current focus and plans.
 
@@ -38,6 +39,7 @@ ox
 | [Quickstart](docs/guide/quickstart.md)          | Install, first run, basic usage                 |
 | [Configuration](docs/guide/configuration.md)    | API credentials, model selection, environment   |
 | [Instruction Files](docs/guide/instructions.md) | CLAUDE.md / AGENTS.md setup and discovery rules |
+| [Sessions](docs/guide/sessions.md)              | Session persistence, listing, and resume        |
 
 ## Building from Source
 
 
@@ -17,6 +17,7 @@ anyhow.workspace = true
 clap.workspace = true
 crossterm.workspace = true
 dirs.workspace = true
+fs4.workspace = true
 futures.workspace = true
 globset.workspace = true
 ignore.workspace = true
 
@@ -233,8 +233,8 @@ pub struct Client {
 }
 
 impl Client {
-    pub fn new(config: Config) -> Result<Self> {
-        let session_id = Uuid::new_v4().to_string();
+    pub fn new(config: Config, session_id: Option<String>) -> Result<Self> {
+        let session_id = session_id.unwrap_or_else(|| Uuid::new_v4().to_string());
         let mut headers = HeaderMap::new();
 
         let mut betas = vec![
 
@@ -1,10 +1,12 @@
 use std::path::{Path, PathBuf};
 use std::time::Duration;
 
-use anyhow::{Context, Result, bail};
+use anyhow::{Context, Result, anyhow, bail};
 use serde::{Deserialize, Serialize};
 use tracing::warn;
 
+use crate::util::lock;
+
 const OAUTH_TOKEN_URL: &str = "https://platform.claude.com/v1/oauth/token";
 const OAUTH_CLIENT_ID: &str = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
 const OAUTH_SCOPES: &[&str] = &[
@@ -17,8 +19,9 @@ const OAUTH_SCOPES: &[&str] = &[
 const TOKEN_EXPIRY_BUFFER_MS: u64 = 5 * 60 * 1000;
 const REFRESH_TIMEOUT: Duration = Duration::from_secs(15);
 
-const LOCK_MAX_RETRIES: u32 = 5;
-const LOCK_RETRY_INTERVAL: Duration = Duration::from_millis(1000);
+/// Directory mtime threshold above which an existing lock is treated
+/// as stale and removed before re-attempting acquisition. Guards
+/// against a peer that crashed without cleaning up its lock dir.
 const LOCK_STALE_THRESHOLD: Duration = Duration::from_secs(30);
 
 #[cfg(target_os = "macos")]
@@ -306,36 +309,36 @@ impl Drop for LockGuard {
     }
 }
 
-/// Acquire a directory-based lock, compatible with `proper-lockfile` (used by
-/// Claude Code). Retries with fixed interval and breaks stale locks.
+/// Acquire a directory-based lock, compatible with `proper-lockfile`
+/// (used by Claude Code). Retries contended locks via the shared
+/// [`lock::retry_acquire`] helper and breaks stale lock directories
+/// on each attempt.
 async fn acquire_lock(path: &Path) -> Result<LockGuard> {
-    for attempt in 0..=LOCK_MAX_RETRIES {
-        match std::fs::create_dir(path) {
-            Ok(()) => {
-                return Ok(LockGuard {
-                    path: path.to_owned(),
-                });
-            }
+    lock::retry_acquire(
+        || match std::fs::create_dir(path) {
+            Ok(()) => Ok(Some(LockGuard {
+                path: path.to_owned(),
+            })),
             Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
                 if is_stale_lock(path) {
                     _ = std::fs::remove_dir_all(path);
-                    continue;
                 }
-                if attempt == LOCK_MAX_RETRIES {
-                    bail!(
-                        "failed to acquire credentials lock after {LOCK_MAX_RETRIES} retries \
-                         — another process may be refreshing"
-                    );
-                }
-                tokio::time::sleep(LOCK_RETRY_INTERVAL).await;
-            }
-            Err(e) => {
-                return Err(e)
-                    .with_context(|| format!("failed to create lock at {}", path.display()));
+                Ok(None)
             }
-        }
-    }
-    unreachable!()
+            Err(e) => Err(anyhow::Error::new(e)
+                .context(format!("failed to create lock at {}", path.display()))),
+        },
+        lock::MAX_RETRIES,
+        lock::RETRY_INTERVAL,
+        || {
+            anyhow!(
+                "failed to acquire credentials lock after {} retries \
+                 — another process may be refreshing",
+                lock::MAX_RETRIES,
+            )
+        },
+    )
+    .await
 }
 
 fn is_stale_lock(path: &Path) -> bool {
Original file line number	Diff line number	Diff line change
`@@ -233,8 +233,8 @@ pub struct Client {`
`233`	`233`	`}`
`234`	`234`
`235`	`235`	`impl Client {`
`236`		`- pub fn new(config: Config) -> Result<Self> {`
`237`		`- let session_id = Uuid::new_v4().to_string();`
	`236`	`+ pub fn new(config: Config, session_id: Option<String>) -> Result<Self> {`
	`237`	`+ let session_id = session_id.unwrap_or_else(\|\| Uuid::new_v4().to_string());`
`238`	`238`	`let mut headers = HeaderMap::new();`
`239`	`239`
`240`	`240`	`let mut betas = vec![`