ingest: fix tailer schema/idempotency/timestamp bugs; add Cowork coverage + reimport recovery

The passive tailer (Tier 1a) has been silently non-functional since it was
written: every usage_events row in the live DB had source='hook', zero from
source='tailer', even though the tailer was running and reading every
tracked file to EOF. Three separate bugs, found while investigating why
desktop-app Cowork sessions weren't showing up:

1. internal/ingest/parser.go read usage/session_id/message_id/model off the
   top level of each JSON line. Real Claude Code transcripts nest usage/id/
   model under a "message" object with camelCase "sessionId" as a sibling —
   the same shape cmd/clusage-cli/hook.go already parses correctly, with a
   comment noting the original parser was written against a mock schema
   that never matched a real transcript. parser_test.go and tailer_test.go
   were fixtured against the same wrong flat schema, which is exactly what
   let this hide: the parser and its tests agreed with each other, just not
   with reality.

2. The tailer's INSERT lacked the idempotent-duplicate handling
   server.go's handleLog already has for hook re-posts. Once (1) was fixed,
   every message the hook got to first collided on the
   UNIQUE(session_id, message_id) constraint and was logged as an ERROR
   plus a permanent parse_errors row, on every restart's catch-up poll.
   Moved the constraint-violation check into store.IsUniqueConstraintViolation
   (shared by both ingest paths) and made the tailer treat a collision as
   idempotent re-delivery: debug-log, skip, still advance the offset.

3. The tailer's INSERT passed occurred_at as a raw time.Time instead of
   store.FormatTime(...), the one documented invariant every other insert
   site in the codebase already follows. modernc.org/sqlite serializes an
   unconverted time.Time via Go's default String() ("2026-07-09 23:02:59.894
   +0000 UTC", sometimes with a monotonic-clock "m=+..." suffix from a bare
   time.Now()), which SQLite's strftime() silently fails to parse (NULL, not
   an error). The dashboard's session/weekly burn-down charts bucket events
   with strftime('%s', occurred_at), so every tailer-sourced row broke that
   query for its bucket — the "converting NULL to int64" errors and the
   "No active window" dashboard symptom. Fixed the insert; TestTailerStores
   QueryableTimestamp pins the failure mode directly against strftime.

Cowork ("local agent mode") session coverage:

Each Cowork session runs against its own private, sandboxed .claude home
nested several directories under %APPDATA%\Claude\local-agent-mode-sessions,
completely separate from the user's real ~/.claude/projects that the
primary tailer watches — same JSONL schema, just invisible to it. Added
claude.cowork_sessions_dir (default resolved via APPDATA) and a second
Tailer instance rooted there; its own poll's recursive filepath.Walk
discovers new sessions automatically as they're created, no hook needed.
cmd/trayapp/main.go's tailerGroup aggregates CaughtUp()/Stop() across both
tailers so /healthz and graceful shutdown treat them uniformly (shutdown
previously only knew about the first tailer, a latent bug in the same area
this change touches).

Bulk reimport recovery tool:

A tailer's byte offset records how far a file was *read*, not whether the
lines in that range actually produced a usage_event — bug (1) above left
every pre-existing session's offset sitting at EOF for content that was
never successfully recorded, with no per-line marker to say which lines
those were. There's no way to selectively repair "just the missing ones"
without already knowing which files/sessions are affected. Added:
  - store.DeleteAllTailerOffsets: wipes every persisted offset.
  - ingest.Tailer.Reimport: wipes offsets (in-memory + DB) and re-walks
    the tailer's root from byte 0.
  - POST /admin/reimport: runs Reimport in the background (202 immediately,
    409 if one's already in flight), for every tailer via tailerGroup.
  - clusage-cli reimport [--wait] [--wait-timeout 5m]: triggers it, with
    --wait polling /healthz's tailer_caught_up.
Deliberately slow and wasteful — re-reads every tracked transcript
byte-for-byte and leans entirely on UNIQUE(session_id, message_id) dedup to
discard anything already recorded. Recovery-only, not routine maintenance.
Verified live: recovered 2,426 tailer-sourced events with timestamps
predating the fix, with zero duplication.

Tests added at every layer (parser, tailer, store, server) including
TestTailerReimportRecoversPastOffset, which reproduces the exact bug class
Reimport exists to fix: an offset already at EOF with one message genuinely
missing, verifying recovery without duplicating what's already there.

Docs: docs/data-sources.md (Cowork second root, recovery section),
docs/container-cli.md (reimport subcommand), docs/configuration.md
(cowork_sessions_dir).

Author: vector76

cmd/clusage-cli/main.go

@@ -37,6 +37,8 @@ func main() {
 		cmdConsumption()
 	case "release":
 		cmdRelease()
+	case "reimport":
+		cmdReimport()
 	case "--version":
 		fmt.Printf("clusage-cli v%s\n", Version)
 	case "--help":
@@ -56,6 +58,7 @@ Usage:
   clusage-cli slack [--format json|release-bool|fraction]
   clusage-cli consumption [--period 24h] [--format json|summary]
   clusage-cli release --released-at TS --job-tag TAG --estimated-cost N --slack-at-release N [--window-kind session|weekly]
+  clusage-cli reimport [--wait] [--wait-timeout 5m]
 
 `, Version)
 }
@@ -333,6 +336,76 @@ func cmdRelease() {
 	}
 }
 
+// cmdReimport triggers a full recovery re-walk of every transcript file the
+// trayapp's tailer(s) track, bypassing persisted byte offsets entirely.
+//
+// This is a rare-recovery tool, not routine maintenance: it exists for
+// cases like suspected data loss, a parser bug that silently under-counted
+// past events, or a restored/corrupted database, where it's unknown which
+// specific sessions are affected. It deliberately re-reads every tracked
+// transcript byte-for-byte and leans entirely on the server's
+// UNIQUE(session_id, message_id) dedup to skip anything already correctly
+// recorded — slow and wasteful by design, in exchange for not requiring
+// anyone to name the affected files in advance.
+func cmdReimport() {
+	fs := flag.NewFlagSet("reimport", flag.ExitOnError)
+	wait := fs.Bool("wait", false, "block until the tailer reports caught up (or --wait-timeout elapses)")
+	waitTimeout := fs.Duration("wait-timeout", 10*time.Minute, "max time to wait with --wait")
+	fs.Parse(os.Args[2:])
+
+	client := &http.Client{Timeout: parseTimeout()}
+	resp, err := client.Post(fmt.Sprintf("%s/admin/reimport", hostURL()), "application/json", bytes.NewReader(nil))
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "error: connection refused\n")
+		os.Exit(3)
+	}
+	body, _ := io.ReadAll(resp.Body)
+	resp.Body.Close()
+
+	switch resp.StatusCode {
+	case http.StatusAccepted:
+		fmt.Println(string(body))
+	case http.StatusConflict:
+		fmt.Fprintf(os.Stderr, "error: %s\n", string(body))
+		os.Exit(4)
+	case http.StatusServiceUnavailable:
+		fmt.Fprintf(os.Stderr, "error: %s\n", string(body))
+		os.Exit(5)
+	default:
+		fmt.Fprintf(os.Stderr, "error: %d %s\n", resp.StatusCode, string(body))
+		os.Exit(5)
+	}
+
+	if !*wait {
+		os.Exit(0)
+	}
+
+	fmt.Println("waiting for tailer to catch up...")
+	deadline := time.Now().Add(*waitTimeout)
+	pollClient := &http.Client{Timeout: 5 * time.Second}
+	for time.Now().Before(deadline) {
+		time.Sleep(2 * time.Second)
+		hresp, err := pollClient.Get(fmt.Sprintf("%s/healthz", hostURL()))
+		if err != nil {
+			continue // transient; keep polling until the deadline
+		}
+		var health struct {
+			TailerCaughtUp bool `json:"tailer_caught_up"`
+		}
+		decodeErr := json.NewDecoder(hresp.Body).Decode(&health)
+		hresp.Body.Close()
+		if decodeErr != nil {
+			continue
+		}
+		if health.TailerCaughtUp {
+			fmt.Println("caught up")
+			os.Exit(0)
+		}
+	}
+	fmt.Fprintf(os.Stderr, "error: still not caught up after %s\n", *waitTimeout)
+	os.Exit(5)
+}
+
 func parseTimeout() time.Duration {
 	var ms int64 = 2000
 	if timeoutMs != "" {

cmd/trayapp/main.go

@@ -31,6 +31,40 @@ type pauseToggle struct{ c *slack.Calculator }
 
 func (p pauseToggle) Toggle() { p.c.SetPaused(!p.c.IsPaused()) }
 
+// tailerGroup collects every running Tailer (the primary ~/.claude/projects
+// root plus, when resolved, the Cowork sessions root) so both /healthz
+// reporting and shutdown treat them uniformly instead of the shutdown path
+// only knowing about the first one.
+type tailerGroup []*ingest.Tailer
+
+// CaughtUp reports /healthz status: caught up only when every tailer is.
+func (g tailerGroup) CaughtUp() bool {
+	for _, t := range g {
+		if !t.CaughtUp() {
+			return false
+		}
+	}
+	return true
+}
+
+// Stop stops every tailer in the group, waiting for each in turn.
+func (g tailerGroup) Stop() {
+	for _, t := range g {
+		t.Stop()
+	}
+}
+
+// Reimport triggers a full recovery re-walk on every tailer in the group.
+// Runs synchronously (each Tailer.Reimport call blocks until its own
+// re-walk finishes) — the HTTP handler wrapping this is expected to call
+// it in its own goroutine so a slow, deliberately-inefficient recovery
+// pass doesn't block the request.
+func (g tailerGroup) Reimport() {
+	for _, t := range g {
+		t.Reimport()
+	}
+}
+
 const Version = "0.0.1"
 
 const (
@@ -108,12 +142,25 @@ func main() {
 
 	tailer := ingest.NewTailer(cfg.Claude.ProjectsDir, db, priceTable)
 	tailer.Start()
-	srv.SetTailer(tailer)
+	tailers := tailerGroup{tailer}
+
+	// Cowork ("local agent mode") sessions each get their own private
+	// .claude home nested under CoworkSessionsDir rather than the user's
+	// real ~/.claude, so the primary tailer above never sees them. A second
+	// tailer rooted one level up recursively finds every session's nested
+	// projects/ dir as it's created — same JSONL schema, no hook needed.
+	if cfg.Claude.CoworkSessionsDir != "" {
+		coworkTailer := ingest.NewTailer(cfg.Claude.CoworkSessionsDir, db, priceTable)
+		coworkTailer.Start()
+		tailers = append(tailers, coworkTailer)
+	}
+	srv.SetTailer(tailers)
+	srv.SetReimporter(tailers)
 
 	// stop signals every background loop (retention pruner, windows ticker)
-	// to exit; wg lets shutdown wait for them. The tailer has its own
-	// stopChan + doneChan and is stopped via tailer.Stop() so we don't
-	// double-track it on the WaitGroup.
+	// to exit; wg lets shutdown wait for them. Each tailer has its own
+	// stopChan + doneChan and is stopped via tailers.Stop() so we don't
+	// double-track them on the WaitGroup.
 	stop := make(chan struct{})
 	var wg sync.WaitGroup
 
@@ -205,15 +252,15 @@ waitLoop:
 	cancelHTTP()
 
 	// Phase 2: stop background goroutines (retention pruner, windows
-	// ticker, tailer, tray UI). tailer.Stop is invoked inside the
+	// ticker, tailer, tray UI). tailers.Stop is invoked inside the
 	// goroutine so a stuck tailer is also bounded by the 10s timeout
 	// — otherwise a hung tailer blocks process exit indefinitely.
 	close(stop)
 	cancelTray()
 
 	bgDone := make(chan struct{})
 	go func() {
-		tailer.Stop()
+		tailers.Stop()
 		wg.Wait()
 		close(bgDone)
 	}()

docs/configuration.md

@@ -21,6 +21,12 @@ http:
 
 claude:
   projects_dir: "~/.claude/projects"   # %USERPROFILE%\.claude\projects on Windows
+  # Root of the desktop app's Cowork ("local agent mode") session tree.
+  # Each Cowork session nests its own private .claude home several levels
+  # under this root, so a second tailer walks it recursively. Default
+  # resolves to %APPDATA%\Claude\local-agent-mode-sessions on Windows;
+  # empty (e.g. APPDATA unset) disables this second tailer.
+  cowork_sessions_dir: "%APPDATA%\\Claude\\local-agent-mode-sessions"
 
 # Price table used to compute cost_usd_equivalent when the source did not
 # report it. See docs/data-model.md "Cost source" and "Price table
@@ -112,10 +118,11 @@ suppress it. See `docs/no-active-session.md` for the wiring.
 ## Path placeholders
 
 `%APPDATA%`, `%LOCALAPPDATA%`, `%USERPROFILE%`, and `%HOME%` placeholders
-are expanded inside `database.path`, `claude.projects_dir`, and
-`pricing.table_path` at load time. When the underlying environment
-variable is unset (typical on Linux), the loader falls back to the user's
-home directory so cross-platform configs stay testable.
+are expanded inside `database.path`, `claude.projects_dir`,
+`claude.cowork_sessions_dir`, and `pricing.table_path` at load time. When
+the underlying environment variable is unset (typical on Linux), the
+loader falls back to the user's home directory so cross-platform configs
+stay testable.
 
 `claude.projects_dir` additionally expands a leading `~/` to the user's
 home directory.

docs/container-cli.md

@@ -85,6 +85,38 @@ fi
 
 GET `/healthz`. Exits `0` if healthy.
 
+### `clusage-cli reimport`
+
+POST `/admin/reimport`, triggering a full recovery re-walk of every
+transcript file the trayapp's tailer(s) track, ignoring persisted byte
+offsets entirely.
+
+**Recovery-only — not routine maintenance.** A byte offset records how far
+a file was *read*, not whether the lines in that range actually produced a
+`usage_event`. A parser bug (or any other silent extraction failure) can
+leave an offset sitting at EOF for content that was never successfully
+recorded, with no per-line marker to say which lines those were. There is
+no way to selectively repair "just the missing ones" without already
+knowing which files/sessions are affected — so this re-reads *everything*
+from byte 0 and relies entirely on the `UNIQUE(session_id, message_id)`
+constraint to skip whatever was already correctly recorded (the same
+idempotency contract described in `docs/data-sources.md`). Deliberately
+slow and wasteful: acceptable as a one-time cost for suspected data loss
+(a parser bug, a restored/corrupted database) but not something to run on
+a schedule.
+
+```
+clusage-cli reimport [--wait] [--wait-timeout 5m]
+```
+
+Without `--wait`, the command returns as soon as the trayapp accepts the
+request (202) — the re-walk itself runs in the background. With `--wait`,
+it polls `GET /healthz`'s `tailer_caught_up` field every 2 seconds until
+the re-walk finishes or `--wait-timeout` (default 10m) elapses.
+
+A second `reimport` call while one is already running gets `409` (exit
+code `4`) rather than piling on a redundant concurrent re-walk.
+
 ## Configuration
 
 Environment variables:

docs/data-sources.md

@@ -74,6 +74,49 @@ workflow is whichever requires less change to existing images.
 - **Container path coverage.** See above; the unshared-container case is common enough
   that it shapes the install flow, not just an edge case.
 
+### Second root: Cowork ("local agent mode") sessions
+
+The desktop app's Cowork feature runs Claude Code sessions in a sandboxed
+VM/background mode. Each Cowork session gets its own **private, nested
+`.claude` home** several directories under
+`%APPDATA%\Claude\local-agent-mode-sessions\<workspace>\<id>\local_<uuid>\`
+— its own `.claude/projects/<encoded-cwd>/<session>.jsonl`, distinct from
+the user's real `~/.claude/projects`. The schema is identical (same
+`usage` block), but the primary tailer above never reaches these files
+because they aren't under its root at all.
+
+A second `ingest.Tailer` instance is started against
+`claude.cowork_sessions_dir` (default
+`%APPDATA%\Claude\local-agent-mode-sessions`) alongside the primary one.
+Because the tailer's poll pass does a full recursive `filepath.Walk`, this
+second root picks up newly-created Cowork sessions automatically — no
+per-session registration needed. Both tailers share the same DB and
+dedup key, so there's no risk of double-counting. This is still Tier 1a:
+no hook, no perturbation, just a second recursion root.
+
+Regular desktop-app Claude Code (the embedded pane, as opposed to Cowork)
+writes straight into the normal `~/.claude/projects`, indistinguishable
+from a terminal session — it needs no special handling.
+
+### Recovering from a silent extraction failure
+
+The tailer's per-file byte offset only records how far a file was *read*,
+not whether the lines in that range actually produced a `usage_event`. A
+parser bug — silently returning "no usage block" for a schema it
+misreads — can leave an offset sitting at EOF for content that was never
+successfully recorded, and a normal poll has nothing new to read past that
+offset, so it can't self-heal. There's also no per-line "was this
+ingested" marker, so a *selective* repair isn't possible without already
+knowing which files/sessions are affected.
+
+`clusage-cli reimport` (see `docs/container-cli.md`) is the recovery tool
+for this: it wipes every persisted tailer offset and re-walks every root
+from byte 0, leaning entirely on the `UNIQUE(session_id, message_id)`
+dedup to discard whatever's already correctly recorded. Slow and wasteful
+by design — it re-reads everything — but that's the acceptable cost of
+guaranteed recovery without naming files in advance. Not routine
+maintenance; use it once after fixing a bug like this, not on a schedule.
+
 ### Schema fragility mitigation
 
 The parser should:

internal/config/config.go

@@ -23,6 +23,14 @@ type Config struct {
 
 	Claude struct {
 		ProjectsDir string `yaml:"projects_dir"`
+		// CoworkSessionsDir is the root of the desktop app's Cowork
+		// ("local agent mode") session tree. Each Cowork session nests its
+		// own private .claude home several levels under this root
+		// (<workspace>/<id>/local_<uuid>/.claude/projects/<encoded-cwd>/
+		// <session>.jsonl), so the tailer walks it recursively rather than
+		// treating it as a projects dir directly. Empty disables it (e.g.
+		// non-Windows, where APPDATA isn't set).
+		CoworkSessionsDir string `yaml:"cowork_sessions_dir"`
 	} `yaml:"claude"`
 
 	Pricing struct {
@@ -71,6 +79,7 @@ func Load(path string) (*Config, error) {
 	cfg.HTTP.Port = 27812
 	cfg.HTTP.Bind = []string{"127.0.0.1"}
 	cfg.Claude.ProjectsDir = expandHome("~/.claude/projects")
+	cfg.Claude.CoworkSessionsDir = defaultCoworkSessionsDir()
 	// Empty means "use the resolution chain" (executable dir / app config
 	// dir override, else the embedded built-in table). A non-empty value is
 	// an explicit override. See ingest.ResolvePriceTable.
@@ -107,6 +116,7 @@ func Load(path string) (*Config, error) {
 	// Resolve env-style placeholders in path/dir fields.
 	cfg.Database.Path = expandPlaceholders(cfg.Database.Path)
 	cfg.Claude.ProjectsDir = expandPlaceholders(cfg.Claude.ProjectsDir)
+	cfg.Claude.CoworkSessionsDir = expandPlaceholders(cfg.Claude.CoworkSessionsDir)
 	cfg.Pricing.TablePath = expandPlaceholders(cfg.Pricing.TablePath)
 
 	return &cfg, nil
@@ -146,6 +156,21 @@ func expandPlaceholders(s string) string {
 	return s
 }
 
+// defaultCoworkSessionsDir returns the root of the Claude desktop app's
+// Cowork ("local agent mode") session tree on Windows. Each Cowork session
+// runs against its own private, sandboxed .claude home nested several
+// levels under this root rather than the user's real ~/.claude — the
+// tailer walks it recursively to reach those nested projects/ dirs (see
+// docs/data-sources.md, Tier 1a). Returns "" when APPDATA isn't set (e.g.
+// non-Windows), which disables this second root without erroring.
+func defaultCoworkSessionsDir() string {
+	appData := os.Getenv("APPDATA")
+	if appData == "" {
+		return ""
+	}
+	return filepath.Join(appData, "Claude", "local-agent-mode-sessions")
+}
+
 // expandHome expands a leading ~/ to the user's home directory.
 func expandHome(path string) string {
 	if !strings.HasPrefix(path, "~/") {