spooling 0.2.5__tar.gz → 0.2.7__tar.gz

{spooling-0.2.5/spooling.egg-info → spooling-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spooling
-Version: 0.2.5
+Version: 0.2.7
 Summary: Local session tracker and semantic search for AI coding assistants
 Author: Parsed Analytics, Inc.
 License: MIT
@@ -56,7 +56,7 @@ No Docker, no PostgreSQL, no Node.js required.
 
 ## How it works
 
-**Four commands. Zero cloud.**
+**Three steps. Local by default.**
 
 ### 01   Install
 
@@ -82,6 +82,8 @@ spooling sync      # embed every session for semantic search
 
 ```bash
 spooling search "that redis race condition"
+spooling session list                      # find a session and its id
+spooling session show ses_e6310bd1 -m      # read that session's full text
 spooling stats
 spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 ```
@@ -90,7 +92,7 @@ spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 
 ## Connect Spooling to your AI coding agent
 
-`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `spooling_search`, `spooling_recent_sessions`, `spooling_get_session`, `spooling_workspace_stats`, and `spooling_top_projects`.
+`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `search_sessions` (find a session), `get_session` (read its full conversation by id), `get_stats`, and `list_traces`. See [Tools exposed](#tools-exposed) for the full list.
 
 ### Cursor / Windsurf / Codex / Antigravity
 
@@ -117,7 +119,7 @@ curl -s http://127.0.0.1:3004/mcp \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq
 ```
 
-Should return the five `spool_*` tools. If you get "connection refused", `spooling ui` is not running (or its ports got squatted, run `lsof -ti :3004 | xargs kill -9` and retry).
+Should return the tools listed under [Tools exposed](#tools-exposed). If you get "connection refused", `spooling mcp` (or `spooling ui`) is not running, or something else is using port 3004. Find it with `lsof -i :3004`.
 
 ---
 
@@ -125,7 +127,7 @@ Should return the five `spool_*` tools. If you get "connection refused", `spooli
 
 ### `spooling init`
 
-Check database connection and show which AI coding tool providers are detected on your system. This scans default paths for Codex CLI, GitHub Copilot, Cursor, and Windsurf session data.
+Check that the local database opens and show which AI coding tool providers are detected on your system. This scans the default paths for every supported provider (see [Supported Providers](#supported-providers)).
 
 ```bash
 spooling init
@@ -154,17 +156,48 @@ spooling stats --days 30   # Last 30 days
 
 ### `spooling search <query>`
 
-Semantic search across all your session history using natural language.
+Semantic search across all your session history using natural language. Each result shows the session title **and its session id**, so you can open it with `spooling session show`.
 
 ```bash
 spooling search "snowflake connector"
 spooling search "authentication bug" -n 5
-spooling search "database migration" -p ~/myproject
+spooling search "database migration" -p myproject
+spooling search ses_e6310bd1                # a session id (or prefix) matches that session first
+spooling search "login issue" --cloud       # search your cloud workspace instead
 ```
 
+Session ids work in the query: a full id, a prefix such as `ses_e6310bd1`, or a UUID/hex prefix of 8+ characters. The matching session is ranked first and labelled `(id match)`. `--cloud` search is matched by the server, so ids are shown but not ranked first.
+
 Options:
 - `-n, --limit` - Number of results (default: 10)
-- `-p, --project` - Filter by project name
+- `-p, --project` - Filter by exact project name (see `spooling session list`)
+- `--cloud` - Search the cloud workspace instead of the local database
+
+### `spooling session`
+
+List sessions and read one back by id.
+
+```bash
+spooling session list                         # newest first, with full session ids
+spooling session list --title login -n 10     # filter by title substring
+spooling session list --id e6310bd1           # filter by id substring
+spooling session list --project myproject --cwd ~/code
+
+spooling session show ses_e6310bd1            # summary: model, tokens, cost, tools used
+spooling session show ses_e6310bd1 -m         # plus the full conversation text
+spooling session show ses_e6310bd1 -m --max-chars 300   # truncate each message
+```
+
+`session show` accepts a full session id or any unique prefix. If a prefix matches several sessions, it lists them and exits so you can pick one.
+
+### `spooling optimize`
+
+Compact the local database. Removes duplicated tool-call rows left by older versions (before 0.2.6), truncates oversized previews, embeds any messages missing from search, and runs `VACUUM`. A backup is written next to the database first, and it is safe to re-run. `spooling sync` prints a hint when it finds duplicates.
+
+```bash
+spooling optimize
+spooling optimize --no-backup --no-vacuum --no-embed   # skip individual steps
+```
 
 ### `spooling watch`
 
@@ -336,11 +369,15 @@ the CLI ships with a `spooling cloud` subcommand.
 Send the most recent local sessions up to the cloud:
 
 ```bash
-spooling push                 # 100 sessions, batches of 20
+spooling push                 # syncs local sessions first, then pushes 100 in batches of 20
 spooling push --limit 500     # bigger backfill
+spooling push --no-sync       # push only what is already in the local database
+spooling push --dry-run       # show what would be pushed
 ```
 
-The server upserts by session id, so re-running is safe.
+`push` ingests new provider sessions into the local database before uploading, so you don't need to run `spooling sync` first. The server upserts by session id, so re-running is safe.
+
+To bring sessions from the cloud back down, use `spooling cloud pull`, or `spooling cloud sync` for both directions.
 
 ### Watch (continuous push)
 
@@ -374,8 +411,8 @@ The cloud API at `api.spooling.ai` uses `/v1/` endpoints. Requests require a Bea
 curl -s "https://api.spooling.ai/v1/stats" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 
-# Search (when deployed — falls back to local search on self-hosted)
-curl -s "https://api.spooling.ai/api/search?q=migration&limit=10" \
+# Search (matches session titles and ids)
+curl -s "https://api.spooling.ai/v1/search?q=migration&limit=10" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 ```
 
@@ -450,7 +487,8 @@ the full config snippet so you don't have to remember it.
 |------|---------|
 | `list_traces` | Recent Spooling traces, filterable by provider/project |
 | `get_trace` | Full detail for one trace: header, spans, eval scores |
-| `search_sessions` | Semantic search over embedded session chunks |
+| `search_sessions` | Semantic search over embedded session chunks. Results include `session_id`; a session id in the query matches that session first |
+| `get_session` | Full detail for one session by id or unique prefix, including the conversation text (`include_messages`, `max_messages`, `max_chars`) |
 | `get_stats` | Top-line stats: traces, tokens, cost, errors |
 | `get_top_vendors` | Most-used external vendors by tool-call count |
 | `list_evals` | Recent eval runs, optionally filtered by rubric |
@@ -462,8 +500,15 @@ the full config snippet so you don't have to remember it.
 For MCP clients that only speak stdio, run `spooling mcp --stdio` and register
 it with the command-based form:
 
-```bash
-# MCP config for stdio transport
+```json
+{
+  "mcpServers": {
+    "spooling": {
+      "command": "spooling",
+      "args": ["mcp", "--stdio"]
+    }
+  }
+}
 ```
 
 ---
@@ -539,7 +584,9 @@ spooling/
 │   ├── parser.py            # Session JSONL parser
 │   ├── embeddings.py        # sentence-transformers (all-MiniLM-L6-v2)
 │   ├── ingest.py            # Sync pipeline
-│   ├── search.py            # Numpy cosine similarity search
+│   ├── search.py            # Numpy cosine similarity search (+ session-id matching)
+│   ├── sessions.py          # Session id lookup helpers
+│   ├── optimize.py          # Database dedupe / compaction
 │   ├── stats.py             # Usage statistics
 │   ├── watcher.py           # File watcher (watchdog)
 │   ├── agent.py             # Chat agent (Ollama + Anthropic)
@@ -583,7 +630,6 @@ All optional — defaults work out of the box.
 | `SPOOLING_DB` | `~/.local/share/spooling/spooling.db` | Path to the SQLite database file (`%APPDATA%\spooling\spooling.db` on Windows) |
 | `SPOOLING_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence transformer model |
 | `SPOOLING_UI_HOST` | `127.0.0.1` | API server host |
-| `SPOOLING_UI_PORT` | `3001` | API server port (used by `spooling serve`) |
 | `SPOOLING_UI_DIR` | *(auto-detected)* | Path to the Next.js `ui/` directory (required for `spooling ui`) |
 | `ANTHROPIC_API_KEY` | - | Anthropic API key (alternative to setting in the GUI) |
 
@@ -604,5 +650,5 @@ All optional — defaults work out of the box.
 
 Run `spooling init` to see which providers are detected on your system.
 
-No data is sent to external servers. Everything runs locally.
+Nothing leaves your machine unless you opt in: Spooling Cloud (`spooling push`), a tunnel (`spooling tunnel`), or the Anthropic chat provider. `spooling pricing refresh` downloads public model prices but sends none of your data.
 

{spooling-0.2.5 → spooling-0.2.7}/README.md

@@ -20,7 +20,7 @@ No Docker, no PostgreSQL, no Node.js required.
 
 ## How it works
 
-**Four commands. Zero cloud.**
+**Three steps. Local by default.**
 
 ### 01   Install
 
@@ -46,6 +46,8 @@ spooling sync      # embed every session for semantic search
 
 ```bash
 spooling search "that redis race condition"
+spooling session list                      # find a session and its id
+spooling session show ses_e6310bd1 -m      # read that session's full text
 spooling stats
 spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 ```
@@ -54,7 +56,7 @@ spooling mcp       # MCP server at http://127.0.0.1:3004/mcp
 
 ## Connect Spooling to your AI coding agent
 
-`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `spooling_search`, `spooling_recent_sessions`, `spooling_get_session`, `spooling_workspace_stats`, and `spooling_top_projects`.
+`spooling mcp` exposes an MCP server at `http://127.0.0.1:3004/mcp` (HTTP streamable transport). Any MCP-speaking agent can connect to it and pull context from your local KB mid-conversation. The agent gets tools like `search_sessions` (find a session), `get_session` (read its full conversation by id), `get_stats`, and `list_traces`. See [Tools exposed](#tools-exposed) for the full list.
 
 ### Cursor / Windsurf / Codex / Antigravity
 
@@ -81,7 +83,7 @@ curl -s http://127.0.0.1:3004/mcp \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq
 ```
 
-Should return the five `spool_*` tools. If you get "connection refused", `spooling ui` is not running (or its ports got squatted, run `lsof -ti :3004 | xargs kill -9` and retry).
+Should return the tools listed under [Tools exposed](#tools-exposed). If you get "connection refused", `spooling mcp` (or `spooling ui`) is not running, or something else is using port 3004. Find it with `lsof -i :3004`.
 
 ---
 
@@ -89,7 +91,7 @@ Should return the five `spool_*` tools. If you get "connection refused", `spooli
 
 ### `spooling init`
 
-Check database connection and show which AI coding tool providers are detected on your system. This scans default paths for Codex CLI, GitHub Copilot, Cursor, and Windsurf session data.
+Check that the local database opens and show which AI coding tool providers are detected on your system. This scans the default paths for every supported provider (see [Supported Providers](#supported-providers)).
 
 ```bash
 spooling init
@@ -118,17 +120,48 @@ spooling stats --days 30   # Last 30 days
 
 ### `spooling search <query>`
 
-Semantic search across all your session history using natural language.
+Semantic search across all your session history using natural language. Each result shows the session title **and its session id**, so you can open it with `spooling session show`.
 
 ```bash
 spooling search "snowflake connector"
 spooling search "authentication bug" -n 5
-spooling search "database migration" -p ~/myproject
+spooling search "database migration" -p myproject
+spooling search ses_e6310bd1                # a session id (or prefix) matches that session first
+spooling search "login issue" --cloud       # search your cloud workspace instead
 ```
 
+Session ids work in the query: a full id, a prefix such as `ses_e6310bd1`, or a UUID/hex prefix of 8+ characters. The matching session is ranked first and labelled `(id match)`. `--cloud` search is matched by the server, so ids are shown but not ranked first.
+
 Options:
 - `-n, --limit` - Number of results (default: 10)
-- `-p, --project` - Filter by project name
+- `-p, --project` - Filter by exact project name (see `spooling session list`)
+- `--cloud` - Search the cloud workspace instead of the local database
+
+### `spooling session`
+
+List sessions and read one back by id.
+
+```bash
+spooling session list                         # newest first, with full session ids
+spooling session list --title login -n 10     # filter by title substring
+spooling session list --id e6310bd1           # filter by id substring
+spooling session list --project myproject --cwd ~/code
+
+spooling session show ses_e6310bd1            # summary: model, tokens, cost, tools used
+spooling session show ses_e6310bd1 -m         # plus the full conversation text
+spooling session show ses_e6310bd1 -m --max-chars 300   # truncate each message
+```
+
+`session show` accepts a full session id or any unique prefix. If a prefix matches several sessions, it lists them and exits so you can pick one.
+
+### `spooling optimize`
+
+Compact the local database. Removes duplicated tool-call rows left by older versions (before 0.2.6), truncates oversized previews, embeds any messages missing from search, and runs `VACUUM`. A backup is written next to the database first, and it is safe to re-run. `spooling sync` prints a hint when it finds duplicates.
+
+```bash
+spooling optimize
+spooling optimize --no-backup --no-vacuum --no-embed   # skip individual steps
+```
 
 ### `spooling watch`
 
@@ -300,11 +333,15 @@ the CLI ships with a `spooling cloud` subcommand.
 Send the most recent local sessions up to the cloud:
 
 ```bash
-spooling push                 # 100 sessions, batches of 20
+spooling push                 # syncs local sessions first, then pushes 100 in batches of 20
 spooling push --limit 500     # bigger backfill
+spooling push --no-sync       # push only what is already in the local database
+spooling push --dry-run       # show what would be pushed
 ```
 
-The server upserts by session id, so re-running is safe.
+`push` ingests new provider sessions into the local database before uploading, so you don't need to run `spooling sync` first. The server upserts by session id, so re-running is safe.
+
+To bring sessions from the cloud back down, use `spooling cloud pull`, or `spooling cloud sync` for both directions.
 
 ### Watch (continuous push)
 
@@ -338,8 +375,8 @@ The cloud API at `api.spooling.ai` uses `/v1/` endpoints. Requests require a Bea
 curl -s "https://api.spooling.ai/v1/stats" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 
-# Search (when deployed — falls back to local search on self-hosted)
-curl -s "https://api.spooling.ai/api/search?q=migration&limit=10" \
+# Search (matches session titles and ids)
+curl -s "https://api.spooling.ai/v1/search?q=migration&limit=10" \
   -H "Authorization: Bearer $SPOOLING_KEY"
 ```
 
@@ -414,7 +451,8 @@ the full config snippet so you don't have to remember it.
 |------|---------|
 | `list_traces` | Recent Spooling traces, filterable by provider/project |
 | `get_trace` | Full detail for one trace: header, spans, eval scores |
-| `search_sessions` | Semantic search over embedded session chunks |
+| `search_sessions` | Semantic search over embedded session chunks. Results include `session_id`; a session id in the query matches that session first |
+| `get_session` | Full detail for one session by id or unique prefix, including the conversation text (`include_messages`, `max_messages`, `max_chars`) |
 | `get_stats` | Top-line stats: traces, tokens, cost, errors |
 | `get_top_vendors` | Most-used external vendors by tool-call count |
 | `list_evals` | Recent eval runs, optionally filtered by rubric |
@@ -426,8 +464,15 @@ the full config snippet so you don't have to remember it.
 For MCP clients that only speak stdio, run `spooling mcp --stdio` and register
 it with the command-based form:
 
-```bash
-# MCP config for stdio transport
+```json
+{
+  "mcpServers": {
+    "spooling": {
+      "command": "spooling",
+      "args": ["mcp", "--stdio"]
+    }
+  }
+}
 ```
 
 ---
@@ -503,7 +548,9 @@ spooling/
 │   ├── parser.py            # Session JSONL parser
 │   ├── embeddings.py        # sentence-transformers (all-MiniLM-L6-v2)
 │   ├── ingest.py            # Sync pipeline
-│   ├── search.py            # Numpy cosine similarity search
+│   ├── search.py            # Numpy cosine similarity search (+ session-id matching)
+│   ├── sessions.py          # Session id lookup helpers
+│   ├── optimize.py          # Database dedupe / compaction
 │   ├── stats.py             # Usage statistics
 │   ├── watcher.py           # File watcher (watchdog)
 │   ├── agent.py             # Chat agent (Ollama + Anthropic)
@@ -547,7 +594,6 @@ All optional — defaults work out of the box.
 | `SPOOLING_DB` | `~/.local/share/spooling/spooling.db` | Path to the SQLite database file (`%APPDATA%\spooling\spooling.db` on Windows) |
 | `SPOOLING_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence transformer model |
 | `SPOOLING_UI_HOST` | `127.0.0.1` | API server host |
-| `SPOOLING_UI_PORT` | `3001` | API server port (used by `spooling serve`) |
 | `SPOOLING_UI_DIR` | *(auto-detected)* | Path to the Next.js `ui/` directory (required for `spooling ui`) |
 | `ANTHROPIC_API_KEY` | - | Anthropic API key (alternative to setting in the GUI) |
 
@@ -568,5 +614,5 @@ All optional — defaults work out of the box.
 
 Run `spooling init` to see which providers are detected on your system.
 
-No data is sent to external servers. Everything runs locally.
+Nothing leaves your machine unless you opt in: Spooling Cloud (`spooling push`), a tunnel (`spooling tunnel`), or the Anthropic chat provider. `spooling pricing refresh` downloads public model prices but sends none of your data.
 

{spooling-0.2.5 → spooling-0.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spooling"
-version = "0.2.5"
+version = "0.2.7"
 description = "Local session tracker and semantic search for AI coding assistants"
 readme = "README.md"
 authors = [{ name = "Parsed Analytics, Inc." }]

{spooling-0.2.5 → spooling-0.2.7}/spooling/cli.py

@@ -71,6 +71,34 @@ def sync(no_embed, provider):
     do_sync(embed=not no_embed, provider_filter=provider)
 
 
+@cli.command()
+@click.option("--no-backup", is_flag=True, help="Skip the pre-optimize database backup")
+@click.option("--no-vacuum", is_flag=True, help="Skip VACUUM (faster, but doesn't reclaim disk space)")
+@click.option("--no-embed", is_flag=True, help="Skip embedding messages that are missing chunks")
+def optimize(no_backup, no_vacuum, no_embed):
+    """Deduplicate and compact the local database.
+
+    Removes duplicated tool-call rows left by older versions, truncates
+    oversized previews, embeds any messages missing chunks, and VACUUMs.
+    A backup is written next to the database first.
+    """
+    from spooling.optimize import optimize as run_optimize
+
+    try:
+        s = run_optimize(
+            backup=not no_backup, vacuum=not no_vacuum, embed=not no_embed,
+            log=lambda m: console.print(m),
+        )
+    except RuntimeError as e:
+        console.print(f"[red]{e}[/red]")
+        raise SystemExit(1)
+    mb = lambda b: f"{b / 2**20:,.0f} MB"
+    console.print(
+        f"[green]Done.[/green] {mb(s['before_bytes'])} -> {mb(s['after_bytes'])} "
+        f"({mb(s['before_bytes'] - s['after_bytes'])} reclaimed)"
+    )
+
+
 @cli.command()
 def watch():
     """Watch for new session data and auto-sync."""
@@ -110,9 +138,13 @@ def search(query, limit, project, cloud_mode):
             f"[dim]{ts[:19]}[/dim]"
             + (f" [cyan](cloud)[/cyan]" if source == "cloud" else "")
         )
-        if r["title"]:
-            console.print(f"   [dim]Session:[/dim] {r['title']}")
-        console.print(f"   {r['content']}")
+        console.print(
+            f"   [dim]Session:[/dim] {r['title'] or '(untitled)'} "
+            f"[cyan]{r['session_id']}[/cyan]"
+            + (" [yellow](id match)[/yellow]" if r.get("match") == "session_id" else "")
+        )
+        if r.get("match") != "session_id":
+            console.print(f"   {r['content']}")
 
 
 @cli.command()
@@ -1113,8 +1145,9 @@ def session():
 @click.option("--project", "-p", default=None, help="Filter by exact project name")
 @click.option("--cwd", default=None, help="Filter by cwd substring")
 @click.option("--title", default=None, help="Filter by title substring")
+@click.option("--id", "id_part", default=None, help="Filter by session id substring")
 @click.option("--limit", "-n", default=20, help="Max sessions to return (default: 20)")
-def session_list(project, cwd, title, limit):
+def session_list(project, cwd, title, id_part, limit):
     """List local sessions with optional filters."""
     from spooling.db import get_connection
     from datetime import datetime as _dt
@@ -1131,6 +1164,9 @@ def session_list(project, cwd, title, limit):
     if title:
         wheres.append("title LIKE ?")
         params.append(f"%{title}%")
+    if id_part:
+        wheres.append("id LIKE ?")
+        params.append(f"%{id_part}%")
     where_clause = ("WHERE " + " AND ".join(wheres)) if wheres else ""
     params.append(limit)
 
@@ -1148,8 +1184,8 @@ def session_list(project, cwd, title, limit):
         return
 
     table = Table(title=f"Sessions ({len(rows)})", show_lines=False)
-    table.add_column("ID", style="dim")
-    table.add_column("Provider", style="cyan")
+    table.add_column("Session ID", style="cyan", no_wrap=True)
+    table.add_column("Provider")
     table.add_column("Project")
     table.add_column("Title")
     table.add_column("Started", style="dim")
@@ -1166,7 +1202,7 @@ def session_list(project, cwd, title, limit):
                 raw_ts = None
         ts = raw_ts.strftime("%m/%d %H:%M") if raw_ts else ""
         table.add_row(
-            (r["id"] or "")[:12],
+            r["id"] or "",
             r["provider_id"] or "",
             _clean_project(r["project"] or ""),
             (r["title"] or "")[:45],
@@ -1180,10 +1216,21 @@ def session_list(project, cwd, title, limit):
 
 @session.command("show")
 @click.argument("session_id")
-@click.option("--messages", "-m", is_flag=True, help="Show full message content")
-def session_show(session_id, messages):
-    """Show full detail for a session including messages and tool calls."""
+@click.option("--messages", "-m", is_flag=True, help="Print the full session text (all messages)")
+@click.option("--max-chars", default=0, type=int, help="Truncate each message to N chars (0 = no limit)")
+def session_show(session_id, messages, max_chars):
+    """Show a session by id (full id or unique prefix), optionally with its full text."""
     from spooling.stats import get_session_detail
+    from spooling.sessions import resolve_session_ids
+
+    matches = resolve_session_ids(session_id)
+    if len(matches) > 1:
+        console.print(f"[yellow]'{session_id}' is ambiguous; matches:[/yellow]")
+        for m in matches:
+            console.print(f"  {m}")
+        raise SystemExit(1)
+    if matches:
+        session_id = matches[0]
 
     detail = get_session_detail(session_id)
     if not detail:
@@ -1216,23 +1263,19 @@ def session_show(session_id, messages):
         console.print(table)
 
     if messages and detail["messages"]:
-        table = Table(title="Messages", show_lines=True)
-        table.add_column("Role", style="cyan", width=10)
-        table.add_column("Timestamp", style="dim", width=18)
-        table.add_column("Content")
         for m in detail["messages"]:
-            content = (m.get("content") or "")[:300]
+            role = m.get("role") or ""
+            color = "green" if role == "user" else "blue"
+            console.print(f"\n[{color}]{role}[/{color}] [dim]{str(m.get('timestamp') or '')[:19]}[/dim]")
+            content = m.get("content") or ""
+            if max_chars and len(content) > max_chars:
+                content = content[:max_chars] + "..."
+            console.print(content, markup=False, highlight=False)
             if m.get("tool_calls"):
                 tools = ", ".join(tc["name"] for tc in m["tool_calls"])
-                content += f"\n[dim]Tools: {tools}[/dim]"
-            table.add_row(
-                m.get("role", ""),
-                str(m.get("timestamp") or "")[:18],
-                content,
-            )
-        console.print(table)
+                console.print(f"Tools: {tools}", style="dim", markup=False)
     elif not messages and detail["messages"]:
-        console.print(f"[dim]{len(detail['messages'])} messages — pass --messages to show content[/dim]")
+        console.print(f"[dim]{len(detail['messages'])} messages — pass --messages to print the session text[/dim]")
 
 
 # ---------------------------------------------------------------------------

{spooling-0.2.5 → spooling-0.2.7}/spooling/cloud.py

@@ -454,6 +454,33 @@ def _push_batches(
     return total, rejected, None
 
 
+def _sync_local(log=console.print) -> None:
+    """Ingest new/updated provider sessions into the local DB before pushing.
+
+    `push` only reads the local DB, so without this step sessions created since
+    the last `spooling sync` (or `spooling watch`) would be silently skipped.
+    Embeddings are skipped (push doesn't use them and they dominate runtime);
+    run `spooling sync` or `spooling watch` for local semantic search.
+    A failure here is non-fatal: we warn and push whatever is already local.
+    """
+    from spooling.ingest import sync as do_sync
+
+    log("[dim]Syncing local sessions before push…[/dim]")
+    try:
+        do_sync(embed=False)
+    except Exception as e:  # noqa: BLE001
+        log(f"[yellow]Local sync failed ({e}); pushing what's already in the local DB.[/yellow]")
+
+
+_SYNC_OPTION = click.option(
+    "--sync/--no-sync",
+    "do_sync",
+    default=True,
+    show_default=True,
+    help="Ingest new provider sessions into the local DB before pushing. Use --no-sync to push only what is already local.",
+)
+
+
 @click.command()
 @click.option("--limit", default=100, help="Max sessions to push per run")
 @click.option("--batch", default=20, help="Sessions per request")
@@ -496,7 +523,8 @@ def _push_batches(
     is_flag=True,
     help="Skip the client-side secret redactor. By default spool scrubs secrets (Snowflake/AWS/GitHub/OpenAI/Anthropic/Stripe tokens, PEM private keys, KEY=VALUE lines whose key looks sensitive) before pushing. Use this only if you're sure the content is clean and you need raw values.",
 )
-def push(limit: int, batch: int, project: str | None, cwd_substr: str | None, title_substr: str | None, dry_run: bool, copy: bool, with_spans: bool, no_redact: bool):
+@_SYNC_OPTION
+def push(limit: int, batch: int, project: str | None, cwd_substr: str | None, title_substr: str | None, dry_run: bool, copy: bool, with_spans: bool, no_redact: bool, do_sync: bool):
     """Push local sessions up to Spooling Cloud.
 
     Without filters, this pushes the most recent ``--limit`` sessions from
@@ -531,6 +559,8 @@ def push(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
         return
     headers = _auth_headers()
     base = _api_base()
+    if do_sync:
+        _sync_local()
     sessions = _collect_sessions(
         limit=limit,
         since=None,
@@ -638,7 +668,8 @@ def push(limit: int, batch: int, project: str | None, cwd_substr: str | None, ti
     is_flag=True,
     help="Skip the client-side secret redactor (see `spooling push --help`).",
 )
-def cloud_watch(interval: int, limit: int, batch: int, lookback: int, no_redact: bool):
+@_SYNC_OPTION
+def cloud_watch(interval: int, limit: int, batch: int, lookback: int, no_redact: bool, do_sync: bool):
     """Continuously push new local sessions to Spooling Cloud (Ctrl+C to stop)."""
     headers = _auth_headers()
     base = _api_base()
@@ -663,6 +694,9 @@ def cloud_watch(interval: int, limit: int, batch: int, lookback: int, no_redact:
         headers = _auth_headers()
         since = (watermark - timedelta(minutes=lookback)) if watermark else None
 
+        if do_sync:
+            _sync_local(log=lambda *_a, **_k: None)
+
         try:
             sessions = _collect_sessions(limit=limit, since=since)
         except Exception as e: