migrations/20260308173619_create-sessions-and-crumbs.sql (1)

13-20: Add an index for session-scoped crumb listing.

The new read path filters by session_id and orders by created_at; without a matching index, this becomes a scan + sort as crumbs grows.

Suggested change

 CREATE TABLE crumbs (
     id INTEGER PRIMARY KEY NOT NULL,
     session_id INTEGER NOT NULL,
     message TEXT NOT NULL,
     state TEXT,
     created_at INTEGER NOT NULL,
     FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
 );
+
+CREATE INDEX idx_crumbs_session_id_created_at
+    ON crumbs(session_id, created_at);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@migrations/20260308173619_create-sessions-and-crumbs.sql` around lines 13 -
20, Add a composite index to speed up session-scoped crumb queries that filter
by session_id and order by created_at: create an index on crumbs(session_id,
created_at) (or crumbs(session_id, created_at DESC) if you always sort
newest-first) so that queries against the crumbs table using session_id and
ordering by created_at use the index; name it something like
idx_crumbs_session_created_at and add the CREATE INDEX statement in the same
migration so it runs alongside the crumbs table creation.

.github/workflows/main.yml (1)

69-78: SQLx versions are currently aligned; ensure SQLX_VERSION stays synchronized with workspace dependencies during updates.

The workflow pins SQLX_VERSION: 0.8.6, which matches both Cargo.toml (0.8.6) and Cargo.lock (0.8.6 across all sqlx packages). However, cargo sqlx prepare --check is sensitive to CLI/crate version misalignment. When bumping SQLx in the future, remember to update both Cargo.toml and the SQLX_VERSION environment variable in lockstep to avoid unexpected failures.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/main.yml around lines 69 - 78, The workflow pins
SQLX_VERSION (used by the Install sqlx-cli step) to 0.8.6; when updating the
sqlx crate you must update SQLX_VERSION in the env block to match the workspace
Cargo.toml/Cargo.lock version so `cargo sqlx prepare --check` stays
compatible—locate SQLX_VERSION and SQLX_FEATURES in the .github workflow and set
SQLX_VERSION to the same version string as the sqlx dependency in Cargo.toml
(and update Cargo.lock via cargo update) whenever you bump sqlx.

docs/storage.md (1)

27-27: Minor documentation inaccuracy: column name.

The documentation refers to session_id as a field, but the actual migration defines the primary key column as id (see migrations/20260308173619_create-sessions-and-crumbs.sql). Consider updating to id for accuracy, or clarifying that session_id refers to the conceptual identifier exposed via the API.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/storage.md` at line 27, Update the docs to match the actual schema:
replace the reference to `session_id` in docs/storage.md with the primary key
column name `id` (as defined in
migrations/20260308173619_create-sessions-and-crumbs.sql), or explicitly note
that `session_id` is the API-level identifier that maps to the `id` column in
the database; ensure the documentation uses `id` when referring to the DB column
and clarifies any API-to-DB naming differences.

docs/cli.md (1)

18-18: Minor inconsistency: task_title vs title terminology.

The documentation uses task_title (lines 18, 28, 44), but the actual CLI argument defined in src/args.rs is named title. Consider aligning the documentation terminology with the code to avoid confusion.

📝 Suggested terminology fix

-- `agent_name` and `task_title` are required at the start of the session.
+- `agent_name` and `title` are required at the start of the session.

-- `task_title`: a short human-readable title describing the task
+- `title`: a short human-readable title describing the task

-- `task_title` is a required display label, not the session identifier.
+- `title` is a required display label, not the session identifier.

Also applies to: 28-28, 44-44

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/cli.md` at line 18, Documentation uses the term "task_title" but the
actual CLI argument is named "title"; update all occurrences of "task_title"
(including the instances on lines 18, 28, 44) to "title" so the docs match the
CLI argument name (also keep "agent_name" as-is), ensuring any examples or
descriptions reference the CLI arg "title" used by the Args/CLI definition.

src/cmds/mod.rs (2)

128-140: Inconsistent validation: session_id not validated in handle_list_crumbs.

Unlike handle_log_crumb (line 100), which validates session_id via SessionId::try_from, this function passes the raw i64 directly to get_crumbs. For consistency and to reject invalid inputs early (e.g., negative IDs), consider adding validation here as well.

♻️ Add session_id validation for consistency

 pub async fn handle_list_crumbs(
     pool: &Pool<Sqlite>,
     session_id: i64,
 ) -> Result<(), ListCrumbsError> {
+    let session_id = SessionId::try_from(session_id)
+        .map_err(|msg| ListCrumbsError::Unexpected(anyhow::anyhow!(msg)))?;
-    let crumbs = get_crumbs(pool, session_id).await?;
+    let crumbs = get_crumbs(pool, session_id.get()).await?;
 
     println!(
         "{}",

Alternatively, you could add an InvalidInput variant to ListCrumbsError for symmetry with other error types.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/cmds/mod.rs` around lines 128 - 140, handle_list_crumbs currently accepts
a raw i64 session_id and calls get_crumbs directly; add the same input
validation used in handle_log_crumb by converting the i64 into SessionId via
SessionId::try_from(session_id) and return/map any conversion error into an
appropriate ListCrumbsError (or add an InvalidInput variant) before calling
get_crumbs with the validated SessionId; update the call site in
handle_list_crumbs to pass the validated SessionId and ensure error mapping
matches the existing error-handling pattern.

---

70-70: Consider logging when current_branch fails.

Using unwrap_or(None) silently swallows git errors (e.g., git not installed, command failures). While treating failures as "no branch" is reasonable for non-git directories, logging a debug/warning message would aid troubleshooting when the user expects branch detection to work.

♻️ Optional: Add tracing for git failures

-    let branch = current_branch(&path).unwrap_or(None);
+    let branch = current_branch(&path).unwrap_or_else(|e| {
+        tracing::debug!("couldn't determine git branch: {e}");
+        None
+    });

Note: This would require adding tracing as a dependency if not already present.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/cmds/mod.rs` at line 70, Replace the silent unwrap_or(None) on
current_branch(&path) with error-aware handling: call current_branch(&path),
match its Result, and on Err log a debug/warning that includes the error and the
path (e.g., using tracing::debug!/warn!), while still treating errors as None
for downstream logic; leave the successful Ok(Some(branch)) and Ok(None) paths
unchanged. Ensure you reference the branch variable assignment (previously let
branch = current_branch(&path).unwrap_or(None);) and import/use tracing if not
already present.