@jhizzard/termdeck 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/client/public/app.js

@@ -129,6 +129,12 @@
       // Sprint 37 T1: orchestrator Guide right-rail. Lazy — fetches the doc
       // on first expand to keep page load light.
       setupGuideRail();
+
+      // 2026-05-08 hotfix: document-level capture-phase image-paste handler.
+      // Intercepts Cmd+V image data before xterm-helper-textarea consumes it
+      // (xterm reads only text/plain, drops images silently). See comment on
+      // setupGlobalImagePaste() near uploadFilesAndType() for details.
+      setupGlobalImagePaste();
     }
 
     // ===== Drag/drop reorder of PTY panels (Sprint 42 T4) =====
@@ -275,6 +281,57 @@
       }
     }
 
+    // Document-level capture-phase image paste handler.
+    //
+    // The Sprint 59 per-panel `paste` listener at line 218 is bubble-phase, but
+    // xterm.js@5.5.0's hidden helper-textarea has its own `paste` handler that
+    // reads only `clipboardData.getData('text/plain')`. Image data lives in
+    // `clipboardData.items` with `kind: 'file'` and never reaches xterm's
+    // text path — and the panel-level bubble-phase handler runs after xterm's,
+    // by which point xterm has already returned (silently dropping the image).
+    // Net: pre-fix, Cmd+V'ing a screenshot into a focused TermDeck panel did
+    // nothing. Joshua reported this on 2026-05-08 (post-v1.1.0 upgrade).
+    //
+    // Fix: document-level listener with `{capture: true}` runs in capture
+    // phase BEFORE the event reaches xterm-helper-textarea. If the event
+    // target is inside a `.term-panel` AND the clipboard contains image
+    // files, we preventDefault + stopPropagation (so xterm + the bubble-phase
+    // panel handler don't see it) and route through `uploadFilesAndType`.
+    // For text paste (no image files) we let the event continue normally.
+    //
+    // Idempotent: setupGlobalImagePaste() is called once from init().
+    let _globalImagePasteSetup = false;
+    function setupGlobalImagePaste() {
+      if (_globalImagePasteSetup) return;
+      _globalImagePasteSetup = true;
+      document.addEventListener('paste', (e) => {
+        const target = e.target;
+        if (!(target instanceof Element)) return;
+        const panel = target.closest('.term-panel');
+        if (!panel) return;
+        const items = (e.clipboardData && e.clipboardData.items) || [];
+        const blobs = [];
+        for (const item of items) {
+          if (item.kind === 'file' && item.type && item.type.startsWith('image/')) {
+            const blob = item.getAsFile();
+            if (blob) blobs.push(blob);
+          }
+        }
+        if (blobs.length === 0) return;
+        e.preventDefault();
+        e.stopPropagation();
+        const ts = new Date().toISOString().replace(/[:.]/g, '-');
+        const named = blobs.map((b, i) => {
+          const ext = (b.type.split('/')[1] || 'png').replace(/[^a-z0-9]/gi, '');
+          const name = b.name && b.name.length > 0
+            ? b.name
+            : `pasted-${ts}${blobs.length > 1 ? '-' + i : ''}.${ext}`;
+          return new File([b], name, { type: b.type });
+        });
+        uploadFilesAndType(panel, named);
+      }, { capture: true });
+    }
+
     // ===== Create Terminal Panel =====
     function createTerminalPanel(sessionData) {
       const id = sessionData.id;

package/packages/server/src/index.js

@@ -16,7 +16,25 @@ const { createCachedLookup, createFailureLogger } = require('./rumen-pool-resili
 // Conditional imports (graceful fallback if not installed yet)
 let pty, Database, pg;
 try { pty = require('@homebridge/node-pty-prebuilt-multiarch'); } catch { pty = null; }
-try { Database = require('better-sqlite3'); } catch { Database = null; }
+try {
+  Database = require('better-sqlite3');
+} catch (err) {
+  // Brad Heath 2026-05-11: distinguish a native-ABI mismatch (Node upgraded
+  // after install) from "package not installed yet." ABI mismatch leaves
+  // Database=null and cascades into a null-handle storm downstream that
+  // masquerades as "Mnestra unreachable / DB timeout" in health probes.
+  // Fail fast with the actionable rebuild hint instead.
+  const msg = err && err.message ? String(err.message) : '';
+  if (err && err.code === 'ERR_DLOPEN_FAILED' && /NODE_MODULE_VERSION/.test(msg)) {
+    console.error('[db] better-sqlite3 native ABI mismatch (Node was upgraded after install).');
+    console.error('[db] TermDeck cannot serve memory features without a working SQLite.');
+    console.error('[db] Fix:');
+    console.error('       cd "$(npm root -g)/@jhizzard/termdeck" && npm rebuild better-sqlite3');
+    console.error('[db] Then restart TermDeck. Aborting.');
+    process.exit(1);
+  }
+  Database = null;
+}
 try { pg = require('pg'); } catch { pg = null; }
 
 // Module-level singleton Postgres pool for rumen_insights (petvetbid DB).

package/packages/server/src/setup/migrations.js

@@ -110,7 +110,33 @@ const MIGRATION_PROBES = Object.freeze({
   '018_rumen_processed_at.sql':
     "select 1 from information_schema.columns where table_schema='public' and table_name='memory_sessions' and column_name='rumen_processed_at'",
   '019_security_hardening.sql':
-    "select 1 from pg_proc p, unnest(coalesce(p.proconfig,'{}'::text[])) c where p.proname='memory_hybrid_search' and c like 'search_path=%' and c like '%extensions%'"
+    "select 1 from pg_proc p, unnest(coalesce(p.proconfig,'{}'::text[])) c where p.proname='memory_hybrid_search' and c like 'search_path=%' and c like '%extensions%'",
+  // 021 canonicalizes legacy gorgias / gorgias-ticket-monitor project tags to
+  // claimguard. Probe is NOT-EXISTS-shaped: returns 1 row when both legacy
+  // tags carry zero rows (021's effects are in place OR the install never had
+  // legacy data). Returns 0 rows when at least one legacy tag still has rows
+  // (021 has not yet run). False-positive backfill costs nothing because the
+  // migration's UPDATE is gated on `project IN ('gorgias', 'gorgias-ticket-monitor')`
+  // so a re-apply against an already-canonicalized corpus is a 0-row no-op.
+  // Sprint 62 T2 added this; 020 is bootstrap-special-cased and intentionally
+  // absent from MIGRATION_PROBES.
+  '021_project_tag_canonicalize_claimguard.sql':
+    "select 1 where not exists (select 1 from memory_items where project in ('gorgias', 'gorgias-ticket-monitor'))",
+  // 022 backfills source_agent for the rows where the writer is inferable from
+  // row shape (Predicate A: decision/bug_fix/architecture/preference/code_context
+  // → 'claude'; Predicate B: fact rows with source_session_id → 'claude';
+  // Predicate D: document_chunk → 'orchestrator'). Predicate C (fact rows
+  // with no session and no path) is intentionally NOT backfilled — see the
+  // migration body for the provenance-preservation rationale. Probe is
+  // NOT-EXISTS-shaped over the A/B/D row-set: returns 1 when those targets
+  // all have source_agent set (022's effects in place), 0 when any A/B/D
+  // target still has NULL (022 has not yet run). Excludes Predicate C from
+  // the probe predicate so the residual NULL slice doesn't keep the probe
+  // false forever. False-positive backfill costs nothing because the
+  // migration body is gated on `source_agent IS NULL` and a re-apply against
+  // an already-tagged corpus is a 0-row no-op. Sprint 62 T3.
+  '022_source_agent_backfill.sql':
+    "select 1 where not exists (select 1 from memory_items where source_agent is null and (source_type in ('decision','bug_fix','architecture','preference','code_context') or (source_type='fact' and source_session_id is not null) or source_type='document_chunk'))"
 });
 
 // Sprint 61 T2 — self-transactional detection.

package/packages/server/src/setup/mnestra-migrations/021_project_tag_canonicalize_claimguard.sql

@@ -0,0 +1,175 @@
+-- 021_project_tag_canonicalize_claimguard.sql
+-- Sprint 62 T2 — finishes the gorgias / gorgias-ticket-monitor → claimguard
+-- rename that migration 012 (Sprint 41 T2) explicitly scoped out.
+--
+-- Why this exists:
+--   Same project (the ClaimGuard repo at ~/Documents/Unagi/gorgias-ticket-monitor)
+--   was tagged three ways across history. As of 2026-05-08:
+--     - 'claimguard'              ~29 rows  (newest tag, written by the
+--                                            post-Sprint-41 PROJECT_MAP)
+--     - 'gorgias-ticket-monitor' ~245 rows  (mid tag, the on-disk dir name)
+--     - 'gorgias'                ~541 rows  (oldest tag, pre-Sprint-41)
+--
+--   Migration 012's §"What this migration does NOT do" called out the merge
+--   as a separate cleanup pass:
+--
+--     - Does NOT consolidate duplicate tags like 'gorgias' vs
+--       'gorgias-ticket-monitor', 'pvb' vs 'PVB', or 'mnestra' vs 'engram'.
+--       Visible in `SELECT project, count(*) FROM memory_items GROUP BY
+--       project` but a separate cleanup pass.
+--
+--   That separate pass is 021. Sprint 21 T2's earlier rename plan never
+--   landed; Sprint 35's harness-hook fix addressed the upstream PROJECT_MAP
+--   so new rows tag correctly, and Sprint 62 T2 (this migration) closes the
+--   historical-corpus gap so memory_recall(project="claimguard") returns the
+--   full ~815-row history rather than just the post-Sprint-41 tail.
+--
+-- The companion T2 invariant test at
+-- termdeck/tests/project-tag-invariant.test.js currently skips the claimguard
+-- invariant via `deferredToSprint35`; with 021 applied that invariant would
+-- pass cleanly if un-deferred. Un-deferring is out of T2's lane (test edits
+-- are owned by orchestrator close-out).
+--
+-- Why the *project*-column merge and not a content-keyword rebucket: rows
+-- already-tagged 'gorgias' or 'gorgias-ticket-monitor' carry definitive
+-- project provenance — the row is from the ClaimGuard project by virtue of
+-- the writer's prior tag, regardless of content keywords. We are not
+-- inferring; we are renaming an exact-match tag set that the SOURCE-BRIEF
+-- and 012's prologue both confirm refer to the same on-disk codebase.
+--
+-- Idempotence:
+--   The UPDATE is gated by `WHERE project IN ('gorgias','gorgias-ticket-monitor')`.
+--   After the first apply those rows carry project='claimguard', so a re-run
+--   matches zero rows — RAISE NOTICE prints 0 and the migration succeeds. The
+--   bundled migration runner (packages/server/src/setup/migration-runner.js)
+--   also checksums applied migrations into mnestra_migrations (table from
+--   020) and skips re-application by filename, so the in-runner path is
+--   idempotent at two layers.
+--
+-- RLS posture:
+--   memory_items has RLS enabled (per migration 019 security hardening), but
+--   service_role bypasses RLS. The migration runner authenticates as
+--   service_role via DATABASE_URL, so the UPDATE lands without policy
+--   changes. This migration does NOT touch policies or roles.
+--
+-- Reversibility:
+--   Down-migration is documented at the bottom (commented). Splitting the
+--   merged set back into three is destructive — once project='claimguard'
+--   replaces the prior values, the row provenance for which tag it ORIGINALLY
+--   carried is gone (no audit column tracks pre-image). Reversal requires
+--   restore from a pg_dump snapshot taken before the migration was applied.
+--   Do NOT attempt heuristic reversal.
+--
+-- Application:
+--   Applied via the bundled migration runner using node-postgres
+--   client.query(). DO blocks + GET DIAGNOSTICS ROW_COUNT (no psql
+--   metacommands — \gset / \echo / etc are not supported in client.query).
+--   Manual fallback: `psql "$DATABASE_URL" -f 021_project_tag_canonicalize_claimguard.sql`.
+
+BEGIN;
+
+-- ============================================================
+-- AUDIT BEFORE
+-- ============================================================
+DO $$
+DECLARE
+  before_claimguard               int;
+  before_gorgias                  int;
+  before_gorgias_ticket_monitor   int;
+  before_total_three              int;
+BEGIN
+  SELECT count(*) INTO before_claimguard
+    FROM public.memory_items WHERE project = 'claimguard';
+  SELECT count(*) INTO before_gorgias
+    FROM public.memory_items WHERE project = 'gorgias';
+  SELECT count(*) INTO before_gorgias_ticket_monitor
+    FROM public.memory_items WHERE project = 'gorgias-ticket-monitor';
+  before_total_three := before_claimguard + before_gorgias + before_gorgias_ticket_monitor;
+  RAISE NOTICE '[021-canonicalize] BEFORE  claimguard=% gorgias=% gorgias-ticket-monitor=%  (sum=%)',
+    before_claimguard, before_gorgias, before_gorgias_ticket_monitor, before_total_three;
+END $$;
+
+-- ============================================================
+-- CANONICALIZE — gorgias + gorgias-ticket-monitor → claimguard
+--
+-- Single-statement UPDATE on the project column. No content scoping required:
+-- the source tags refer unambiguously to the ClaimGuard project per Sprint 41
+-- T2's analysis (012's prologue) and the SOURCE-BRIEF for Sprint 62 §1.
+-- ============================================================
+DO $$
+DECLARE
+  affected_count integer;
+BEGIN
+  UPDATE public.memory_items
+     SET project = 'claimguard'
+   WHERE project IN ('gorgias', 'gorgias-ticket-monitor');
+  GET DIAGNOSTICS affected_count = ROW_COUNT;
+  RAISE NOTICE '[021-canonicalize] canonicalized % memory_items rows  (gorgias + gorgias-ticket-monitor) -> claimguard',
+    affected_count;
+END $$;
+
+-- ============================================================
+-- AUDIT AFTER + CONSERVATION CHECK
+-- ============================================================
+DO $$
+DECLARE
+  after_claimguard               int;
+  after_gorgias                  int;
+  after_gorgias_ticket_monitor   int;
+BEGIN
+  SELECT count(*) INTO after_claimguard
+    FROM public.memory_items WHERE project = 'claimguard';
+  SELECT count(*) INTO after_gorgias
+    FROM public.memory_items WHERE project = 'gorgias';
+  SELECT count(*) INTO after_gorgias_ticket_monitor
+    FROM public.memory_items WHERE project = 'gorgias-ticket-monitor';
+  RAISE NOTICE '[021-canonicalize] AFTER   claimguard=% gorgias=% gorgias-ticket-monitor=%',
+    after_claimguard, after_gorgias, after_gorgias_ticket_monitor;
+  IF after_gorgias <> 0 OR after_gorgias_ticket_monitor <> 0 THEN
+    RAISE EXCEPTION
+      '[021-canonicalize] post-apply invariant violated: expected zero rows in gorgias / gorgias-ticket-monitor, got gorgias=% gorgias-ticket-monitor=%',
+      after_gorgias, after_gorgias_ticket_monitor;
+  END IF;
+END $$;
+
+COMMIT;
+
+-- ============================================================
+-- POST-APPLY: verification queries (NOT part of the migration; run separately
+-- to confirm the merge took, the invariant tests stay green, and the recall
+-- path returns the full history). Each query is safe to run repeatedly.
+-- ============================================================
+--
+-- 1. Tag distribution after migration — claimguard should be the only
+--    bucket among the three; gorgias / gorgias-ticket-monitor should be 0:
+--      SELECT project, count(*) FROM public.memory_items
+--       WHERE project IN ('claimguard', 'gorgias', 'gorgias-ticket-monitor')
+--       GROUP BY project ORDER BY project;
+--
+-- 2. Confirm no orphan rows remain under either legacy tag (these should
+--    return 0):
+--      SELECT count(*) FROM public.memory_items
+--       WHERE project IN ('gorgias', 'gorgias-ticket-monitor');
+--
+-- 3. Spot-check that the merged set carries content from all three
+--    historical eras (look for varied dates, varied source_types):
+--      SELECT date_trunc('week', created_at) AS week, count(*)
+--        FROM public.memory_items
+--       WHERE project = 'claimguard'
+--       GROUP BY 1 ORDER BY 1;
+--
+-- 4. Confirm the project-tag invariant test for claimguard would now pass
+--    if un-deferred (rows whose content matches gorgias-ticket-monitor or
+--    Unagi/ identifiers should be top-tagged claimguard):
+--      SELECT project, count(*) FROM public.memory_items
+--       WHERE content ILIKE '%gorgias-ticket-monitor%'
+--          OR content ILIKE '%Unagi/%'
+--       GROUP BY project ORDER BY count(*) DESC LIMIT 5;
+--
+-- DOWN-MIGRATION (manual, NOT auto-applied):
+--   Splitting the merged set back into three is non-trivial (no source-of-
+--   truth on which rows were originally which tag — provenance is lost when
+--   the UPDATE replaces the project string). If a roll-back is needed,
+--   restore from a pg_dump taken before this migration was applied. Do NOT
+--   attempt to reverse via heuristic — the row provenance is destroyed by
+--   the merge.

package/packages/server/src/setup/mnestra-migrations/022_source_agent_backfill.sql

@@ -0,0 +1,182 @@
+-- 022_source_agent_backfill.sql
+-- Sprint 62 T3 (TermDeck) — backfill source_agent for pre-Sprint-50 NULL rows
+-- where the writer can be inferred from row shape, NOT from content content-marker
+-- inspection. Mnestra 0.4.9 (release-pending; orchestrator bumps at sprint close).
+--
+-- Why this exists:
+--   Sprint 50 introduced source_agent (migration 015). Pre-Sprint-50 rows
+--   have source_agent IS NULL and are silently excluded from filtered
+--   memory_recall queries (per the recall tool's docstring: "NULL-source-
+--   agent rows ... are excluded when this filter is set" — see
+--   src/recall.ts:165-169).
+--
+--   2026-05-08 production probe: 6,381 of 6,483 active memory_items rows
+--   (~98%) have source_agent IS NULL — far above the SOURCE-BRIEF estimate
+--   of "3,000+". Filtered recall has been blind to most of the corpus for
+--   roughly the entire post-Sprint-50 window.
+--
+--   Migration 015 already backfilled session_summary NULL rows -> 'claude'
+--   (015 lines 48-51), so the NULL universe today is exclusively non-
+--   session_summary types. This migration closes the slice where the
+--   writer can be inferred from row shape (architectural / schema /
+--   structural evidence), and deliberately leaves the remaining slice
+--   NULL — to be reached via the additive include_null_source recall
+--   flag rather than by speculative attribution.
+--
+-- Design principle: row-shape attribution, not content-marker attribution.
+--   The original SOURCE-BRIEF proposed content-marker predicates (ILIKE
+--   '%[T-CODEX]%' etc). Sampling proved this unsafe: 100% of NULL rows
+--   matching codex/gemini/grok markers are Claude *describing* those
+--   agents, never authored by them. Marker == "row mentions agent",
+--   not "row authored by agent".
+--
+--   Instead, this migration attributes by the (source_type, has_path,
+--   has_session) tuple — schema-level fingerprints that map 1:1 to the
+--   writer architecture, and that 50+ randomly-sampled rows confirm.
+--
+-- Predicate plan (each with explicit evidence chain):
+--
+--   A. NULL + source_type IN (decision, bug_fix, architecture, preference,
+--      code_context) -> 'claude'.
+--      Architectural evidence: pre-Sprint-50, only Claude shipped a
+--      memory_remember client. The mcp__memory__memory_remember and
+--      mcp__mnestra__memory_remember surfaces both ran exclusively in
+--      Claude sessions. Codex/Gemini/Grok memory_remember capabilities
+--      did not exist until the Sprint 51 per-agent MCP wiring (see
+--      memory: "MCP server wiring patterns for Codex, Gemini, and Grok
+--      CLIs (verified 2026-05-04 ... follow-up to Sprint 51.6's "Codex
+--      MCP not wired" gap)"). All NULL rows of these source_types are
+--      pre-Sprint-50 and therefore architecturally Claude.
+--      Schema fingerprint: 100% of these rows have source_file_path IS NULL
+--      AND source_session_id IS NULL — bare memory_remember shape.
+--      Sample confirmation: 28-row sample showed 100% Claude-summary writing
+--      pattern (project context, dated entries, file:line evidence — the
+--      recognizable Claude memory_remember signature).
+--      Expected count: 560.
+--
+--   B. NULL + source_type='fact' + source_session_id IS NOT NULL -> 'claude'.
+--      Schema evidence: source_session_id is a Claude session UUID format
+--      (matches the existing claude/session_summary tagged rows; same
+--      shape: has_path=false, has_session=true). The Claude SessionEnd
+--      hook is the only writer that populates source_session_id with a
+--      Claude UUID. Other writers either set source_file_path (rag-extractor)
+--      or leave both NULL (bare memory_remember).
+--      Expected count: 4,587.
+--
+--   D. NULL + source_type='document_chunk' -> 'orchestrator'.
+--      Structural evidence: 951/951 rows have source_file_path set + JSONB
+--      metadata containing chunkIndex + heading keys — unmistakable
+--      rag-system batch-chunker output. The chunker is not an LLM session;
+--      'orchestrator' is the appropriate non-LLM tag per the source_agent
+--      enum (claude|codex|gemini|grok|orchestrator).
+--      Path buckets:
+--        513 rows ~/.gemini/antigravity/scratch/* (Gemini scratch docs the
+--                 rag-extractor ingested — Gemini wrote the source MD,
+--                 but the rag-extractor wrote the row.)
+--        429 rows ~/Documents/* (project docs ingested directly).
+--          9 rows ~/.claude/projects/*/memory/MEMORY.md (auto-memory MD
+--                 ingested by the rag-extractor).
+--      All four buckets are extractor-written, not LLM-written. The
+--      original document author is preserved in source_file_path; the
+--      row writer is the extractor.
+--      Expected count: 951.
+--
+-- Predicate deliberately NOT applied (response to T4-CODEX 20:43 ET concern):
+--   C. NULL + source_type='fact' + source_session_id IS NULL +
+--      source_file_path IS NULL.
+--      These 283 rows are bare memory_remember calls without session
+--      attribution. Sampling (10 rows) showed 100% Claude content pattern,
+--      but they lack the schema fingerprint that makes A/B/D structurally
+--      definitive — there is no architectural lock that PREVENTS a
+--      non-Claude writer from producing this shape (e.g., a manual psql
+--      insert, a non-MCP REST call, or an early rag-extractor variant
+--      that omitted source_file_path).
+--      Migration 015 lines 24-30 explicitly preserved provenance
+--      uncertainty for non-session_summary historical rows; broad
+--      attribution here would erase that bright line. Per T4-CODEX
+--      AUDIT-CONCERN (Sprint 62, 20:43 ET), these rows stay NULL and
+--      are reached via the additive include_null_source recall path
+--      added in src/recall.ts under this same sprint.
+--      Residual NULL after this migration: 283 rows = 4.4% of corpus.
+--      Acceptance target: <5%. Met.
+--
+-- Total backfill: 6,098 rows (A + B + D). Acceptance: residual NULL < 5%
+-- of corpus (4.4% expected; well under threshold).
+--
+-- What this migration deliberately does NOT do:
+--   * Touch session_summary rows (015 already attributed those).
+--   * Touch already-tagged rows (every UPDATE is gated by source_agent IS NULL).
+--   * Use content-marker predicates (sampling proved unreliable; markers
+--     describe agents, not authors).
+--   * Backfill the inferential-only slice (Predicate C, see above).
+--
+-- Idempotent: every UPDATE has WHERE source_agent IS NULL, so re-running
+-- is a no-op on already-tagged rows. Safe to re-apply.
+--
+-- Reversibility: this migration tags rows but does not modify content,
+-- type, or any other column. To revert (in a future migration), run:
+--   UPDATE public.memory_items
+--      SET source_agent = NULL
+--    WHERE source_agent IN ('claude', 'orchestrator')
+--      AND created_at < '2026-05-09'
+--      AND source_type != 'session_summary';  -- preserve 015's backfill
+--
+-- RLS posture (per global CLAUDE.md RLS hygiene gates 1-5): this is a
+-- DO block, not a CREATE FUNCTION. Runs as the migration runner's role
+-- (service_role, which bypasses RLS). search_path is set explicitly to
+-- defend against schema-shadow attacks during execution. No new policies,
+-- no new function executable surface.
+
+set search_path = public, pg_catalog;
+
+do $$
+declare
+  pred_a integer := 0;
+  pred_b integer := 0;
+  pred_d integer := 0;
+  remaining integer;
+  total_rows integer;
+begin
+  -- Predicate A: structural attribution by source_type for non-fact, non-document_chunk
+  -- types. Architectural lock: pre-Sprint-50 only Claude shipped a memory_remember
+  -- client. NULL rows of these types are therefore unambiguously Claude.
+  update public.memory_items
+     set source_agent = 'claude'
+   where source_agent is null
+     and source_type in ('decision', 'bug_fix', 'architecture', 'preference', 'code_context');
+  get diagnostics pred_a = row_count;
+
+  -- Predicate B: fact rows with Claude-session attribution. source_session_id
+  -- is the Claude SessionEnd hook's UUID; same shape as the existing tagged
+  -- claude/session_summary rows.
+  update public.memory_items
+     set source_agent = 'claude'
+   where source_agent is null
+     and source_type = 'fact'
+     and source_session_id is not null;
+  get diagnostics pred_b = row_count;
+
+  -- Predicate D: rag-system document chunks -> 'orchestrator' (non-LLM batch writer).
+  -- All 951 rows carry source_file_path + chunkIndex/heading metadata — the
+  -- rag-extractor's deterministic fingerprint.
+  update public.memory_items
+     set source_agent = 'orchestrator'
+   where source_agent is null
+     and source_type = 'document_chunk';
+  get diagnostics pred_d = row_count;
+
+  select count(*) into remaining
+    from public.memory_items
+   where source_agent is null;
+
+  select count(*) into total_rows from public.memory_items;
+
+  raise notice '[022] backfill complete: A(claude/typed)=% B(claude/fact+session)=% D(orchestrator/doc_chunk)=% remaining_null=% / % total (acceptance: <5%%)',
+    pred_a, pred_b, pred_d, remaining, total_rows;
+  raise notice '[022] residual NULL = bare memory_remember fact rows (no session, no path); reach via include_null_source recall flag';
+end$$;
+
+-- Refresh the column comment to reflect 015 + 022 together as the partial-
+-- backfill story, and document the residual + the recall flag escape hatch.
+comment on column public.memory_items.source_agent is
+  'Agent that produced this memory: claude|codex|gemini|grok|orchestrator|NULL. Populated at write time by per-agent SessionEnd writers from Sprint 50 onward. Pre-Sprint-50 NULL rows backfilled by migration 015 (session_summary -> claude) and migration 022 (decision/bug_fix/architecture/preference/code_context -> claude; fact w/ source_session_id -> claude; document_chunk -> orchestrator). Residual NULL = bare-call fact rows without session or path attribution; intentionally preserved per migration 015''s provenance bright line. Reach those via memory_recall include_null_source=true.';