fix(cloud): repair exported empty sessions

Author: Alan-TheGentleman

docs/engram-cloud/troubleshooting.md

@@ -103,7 +103,7 @@ You may also see the failure only during the final server push, even after `doct
 write chunk: cloud: push chunk ...: status 400: invalid push payload: sessions[N].directory is required
 ```
 
-It means a historical `session` mutation in `sync_mutations` is missing `directory`, a local `sessions` row for the project still has an empty/null `directory`, or a historical `observation` mutation is missing one of the required upsert fields: `sync_id`, `session_id`, `type`, `title`, `content`, or `scope`. Newer Engram versions write these fields correctly, but old journal rows or local session rows may still need repair before first cloud upload.
+It means a historical `session` mutation in `sync_mutations` is missing `directory`, a local `sessions` row included in the project export still has an empty/null `directory`, or a historical `observation` mutation is missing one of the required upsert fields: `sync_id`, `session_id`, `type`, `title`, `content`, or `scope`. Newer Engram versions write these fields correctly, but old journal rows or local session rows may still need repair before first cloud upload.
 
 ### Safe path: helper script
 
@@ -144,7 +144,7 @@ If doctor reveals another legacy blocker after each repair, use loop mode after
 tools/repair-missing-session-directory.sh --apply --interactive --all <project>
 ```
 
-Loop mode repairs exactly one supported blocker (`entity=session|observation op=upsert`), reruns `engram cloud upgrade doctor --project <project>`, then repeats until doctor no longer reports a supported blocker. If doctor reports ready but local `sessions` rows for the project still have empty/null `directory`, loop mode applies that fallback repair and reruns doctor once more. It still stops on unsupported blockers, project mismatches, or observation payloads that cannot be fully inferred. In non-interactive loop mode, rerun with `--interactive` when the script asks for human-provided observation fields.
+Loop mode repairs exactly one supported blocker (`entity=session|observation op=upsert`), reruns `engram cloud upgrade doctor --project <project>`, then repeats until doctor no longer reports a supported blocker. If doctor reports ready but local `sessions` rows included in the project export still have empty/null `directory`, loop mode applies that fallback repair and reruns doctor once more. It still stops on unsupported blockers, project mismatches, or observation payloads that cannot be fully inferred. In non-interactive loop mode, rerun with `--interactive` when the script asks for human-provided observation fields.
 
 If one-shot mode finds no doctor blocker but reports local sessions with empty/null directory, preview and apply the fallback explicitly:
 
@@ -176,7 +176,7 @@ For session repairs, the script patches one legacy row in `sync_mutations` by ad
 "directory": "/absolute/path/to/project"
 ```
 
-It also updates `sessions.directory` only when the matching session row exists and its directory is empty. In the fallback path for `sessions[N].directory is required`, it updates only local `sessions` rows for the requested project where `directory IS NULL OR directory = ''`; it does not modify `sync_mutations`.
+It also updates `sessions.directory` only when the matching session row exists and its directory is empty. In the fallback path for `sessions[N].directory is required`, it updates only local `sessions` rows included in the requested project export scope where `directory IS NULL OR directory = ''`; it does not modify `sync_mutations`.
 
 For observation repairs, the script reads the authoritative local row from `observations` using `payload.sync_id` or `entity_key`, then fills only missing or empty fields in the mutation payload:
 
@@ -252,6 +252,7 @@ If you want to inspect before using the helper:
 sqlite3 ~/.engram/engram.db "select seq, entity, op, entity_key, payload from sync_mutations where seq = 873;"
 sqlite3 ~/.engram/engram.db "select id, project, directory from sessions where id = 'manual-save-current';"
 sqlite3 ~/.engram/engram.db "select id, project, started_at, directory from sessions where project = '<project>' and (directory is null or directory = '');"
+sqlite3 ~/.engram/engram.db "select s.id, s.project, s.started_at, s.directory from sessions s where (s.directory is null or s.directory = '') and (s.project = '<project>' or s.id in (select session_id from observations where ifnull(project, '') = '<project>' union select session_id from user_prompts where ifnull(project, '') = '<project>'));"
 ```
 
 Do not manually edit SQLite without a backup.

tools/repair-missing-session-directory.sh

@@ -284,28 +284,50 @@ empty_session_count() {
     printf '0\n'
     return 0
   fi
+  scope_predicate=$(empty_session_scope_predicate)
+  sqlite_scalar "SELECT COUNT(*) FROM sessions WHERE ifnull(directory, '') = '' AND $scope_predicate;"
+}
+
+empty_session_scope_predicate() {
   PROJECT_SQL=$(sql_escape "$PROJECT")
-  sqlite_scalar "SELECT COUNT(*) FROM sessions WHERE project = '$PROJECT_SQL' AND ifnull(directory, '') = '';"
+  predicate="(project = '$PROJECT_SQL'"
+
+  if have_table observations; then
+    predicate="$predicate OR id IN (
+      SELECT session_id FROM observations
+       WHERE ifnull(project, '') = '$PROJECT_SQL'
+          OR (ifnull(project, '') = '' AND session_id IN (SELECT id FROM sessions WHERE project = '$PROJECT_SQL'))
+    )"
+  fi
+
+  if have_table user_prompts; then
+    predicate="$predicate OR id IN (
+      SELECT session_id FROM user_prompts
+       WHERE ifnull(project, '') = '$PROJECT_SQL'
+          OR (ifnull(project, '') = '' AND session_id IN (SELECT id FROM sessions WHERE project = '$PROJECT_SQL'))
+    )"
+  fi
+
+  printf '%s\n' "$predicate)"
 }
 
 preview_empty_sessions() {
-  PROJECT_SQL=$(sql_escape "$PROJECT")
+  scope_predicate=$(empty_session_scope_predicate)
   info "Affected local sessions:"
   if have_column sessions started_at; then
-    sqlite_box "SELECT id, project, started_at, ifnull(directory, '') AS directory FROM sessions WHERE project = '$PROJECT_SQL' AND ifnull(directory, '') = '' ORDER BY ifnull(started_at, ''), id;" || true
+    sqlite_box "SELECT id, project, started_at, ifnull(directory, '') AS directory FROM sessions WHERE ifnull(directory, '') = '' AND $scope_predicate ORDER BY ifnull(started_at, ''), id;" || true
   else
-    sqlite_box "SELECT id, project, ifnull(directory, '') AS directory FROM sessions WHERE project = '$PROJECT_SQL' AND ifnull(directory, '') = '' ORDER BY id;" || true
+    sqlite_box "SELECT id, project, ifnull(directory, '') AS directory FROM sessions WHERE ifnull(directory, '') = '' AND $scope_predicate ORDER BY id;" || true
   fi
 }
 
 repair_empty_sessions() {
   have_table sessions || die "sessions table not found in DB: $DB"
-  PROJECT_SQL=$(sql_escape "$PROJECT")
   missing_count=$(empty_session_count)
 
   if [ "$missing_count" = "0" ]; then
-    info "No local sessions with empty/null directory found for project '$PROJECT'."
-    return 1
+    info "No local sessions in project export scope with empty/null directory found for project '$PROJECT'."
+    return 0
   fi
 
   DIRECTORY=$(resolve_directory)
@@ -332,12 +354,13 @@ repair_empty_sessions() {
   cp "$DB" "$backup"
   info ""
   info "Backup created: $backup"
+  scope_predicate=$(empty_session_scope_predicate)
 
   sqlite3 -batch "$DB" "BEGIN;
 UPDATE sessions
 SET directory = '$DIRECTORY_SQL'
-WHERE project = '$PROJECT_SQL'
-  AND ifnull(directory, '') = '';
+WHERE ifnull(directory, '') = ''
+  AND $scope_predicate;
 COMMIT;"
 
   remaining_count=$(empty_session_count)
@@ -351,7 +374,7 @@ handle_no_supported_blocker() {
   missing_count=$(empty_session_count)
 
   if [ "$missing_count" != "0" ]; then
-    info "No supported sync_mutations blocker found, but $missing_count local session row(s) for project '$PROJECT' have empty/null directory."
+    info "No supported sync_mutations blocker found, but $missing_count local session row(s) in project export scope for '$PROJECT' have empty/null directory."
     if [ "$FIX_EMPTY_SESSIONS" -eq 1 ] || [ "$ALL" -eq 1 ]; then
       repair_empty_sessions
       return 0
@@ -361,6 +384,9 @@ handle_no_supported_blocker() {
   fi
 
   info "No supported session/observation upsert blocker found."
+  if [ "$FIX_EMPTY_SESSIONS" -eq 1 ]; then
+    info "No local sessions in project export scope with empty/null directory found for project '$PROJECT'."
+  fi
   [ "$context" = "loop" ] && info "Loop mode complete."
   return 1
 }
@@ -369,6 +395,11 @@ if [ ! "$SEQ" ] || [ "$ALL" -eq 1 ]; then
   require_cmd engram
 fi
 
+if [ "$FIX_EMPTY_SESSIONS" -eq 1 ] && [ "$ALL" -ne 1 ] && [ ! "$SEQ" ]; then
+  repair_empty_sessions
+  exit 0
+fi
+
 if [ ! "$SEQ" ] && [ "$ALL" -ne 1 ]; then
   tmp=${TMPDIR:-/tmp}/engram-doctor-output.$$.txt
   trap 'rm -f "$tmp"' EXIT HUP INT TERM