@rulemetric/local 0.12.3 → 0.12.5

package/dist/supabase/migrations/00212_reconcile_junk_session_paths.sql

@@ -0,0 +1,393 @@
+-- Sessions carrying a bare home-directory project_path are repairable, and the
+-- reconciler must chase them.
+--
+-- THE DEFECT CLASS (found 2026-08-27, via "why does Thrakopontia show no
+-- suggestions?"). Until 2026-08-26 the subdir-consolidation normalizer in
+-- POST /api/sessions rewrote real project paths into `/Users/<name>` — home is
+-- a prefix of every path the user works in, and the loop had no home-dir
+-- guard. 219 sessions on the cloud DB carry a bare home path; for 34 of them
+-- the transcript on disk still names the true checkout. Fill-only merge
+-- semantics then froze the junk in place: the very next hook POST carried the
+-- correct cwd and was discarded, and the SessionEnd reimport that would have
+-- corrected it is an unreliable messenger (Claude Code cancels the hook after
+-- its first network call). The path keys real behaviour — insights job
+-- targeting, suggestion project scoping, the session feed's exact-path filter
+-- — so these rows starve their real project of its own evidence.
+--
+-- 00206's producer explicitly EXCLUDED home paths as "orphaned correctly".
+-- That was written before we knew the normalizer had been rewriting real
+-- sessions INTO home: a bare home path is not a fact about where the session
+-- ran, it is (almost always) a fact about what the normalizer did to the row.
+-- The worker-side recovery already treats it that way (recoverAnchors ignores
+-- a home stored path and reads the transcript), and repairAttribution now
+-- upgrades a junk stored path on anchor-backed evidence — this migration makes
+-- the producer and the conformance monitor agree.
+--
+-- Three pieces:
+--   1. enqueue_reconcile_attribution(): junk-path sessions become eligible.
+--   2. suggestion_pipeline_conformance(): new metric + CHECK 6, so the shape
+--      is visible even for users whose worker never runs (their repair lane).
+--   3. Idempotent DELETE of bare-home project_checkouts rows — the laundering
+--      vector by which resolveProjectIdForPath('/Users/<name>') attributed
+--      home-path sessions to an unrelated project. The API guards new inserts
+--      (upsertProjectCheckout refuses home paths) but rows minted by older
+--      API builds still running elsewhere (local-mode installs) would
+--      re-poison resolution.
+-- ---------------------------------------------------------------------------
+
+-- ── 1. Producer: chase junk-path sessions too ──────────────────────────────
+
+create or replace function public.enqueue_reconcile_attribution()
+returns integer
+language plpgsql
+security definer
+set search_path = public
+as $$
+declare
+  queued integer;
+begin
+  with eligible as (
+    select s.user_id
+    from public.sessions s
+    where (
+        s.project_id is null
+        or not exists (
+          select 1 from public.project_checkouts pc where pc.project_id = s.project_id
+        )
+        -- A bare home dir is never a project checkout, so an attributed
+        -- session carrying one is self-contradictory — the pre-2026-08-26
+        -- normalizer shape. The handler repairs it from the transcript on the
+        -- machine that ran it.
+        or s.project_path ~ '^/(Users|home)/[^/]+/?$'
+      )
+      -- Only chase orphans a worker could plausibly still repair. A session
+      -- whose checkout was deleted years ago is permanently unrepairable, and
+      -- re-walking it every hour forever is pure noise. 90 days is well past
+      -- Claude Code's transcript retention, which is the recovery source for
+      -- the pathless shape.
+      and s.started_at > now() - interval '90 days'
+      -- Sessions with no external id cannot be addressed through
+      -- POST /api/sessions at all (it matches on external_session_id), so the
+      -- handler would only count them as unrepairable. Do not enqueue for a
+      -- user who has nothing BUT those.
+      and s.external_session_id is not null
+      -- Temp fixtures are orphaned CORRECTLY. (Home dirs used to sit in this
+      -- exclusion; they are the repair target now — see the header.)
+      and (
+        s.project_path is null
+        or s.project_path !~ '^/(private/)?(tmp|var/folders)'
+      )
+    group by s.user_id
+  ), fresh as (
+    select e.user_id
+    from eligible e
+    -- One in flight at a time, per the 00083/00086 pattern.
+    where not exists (
+      select 1 from public.agent_jobs j
+      where j.task_kind = 'cron_reconcile_attribution'
+        and j.status in ('pending', 'claimed', 'running')
+        and j.user_id = e.user_id
+    )
+    -- Do not re-run within the hour for a user whose last pass just completed.
+    -- The orphan set only changes when new sessions land or a checkout appears.
+    and not exists (
+      select 1 from public.agent_jobs j
+      where j.task_kind = 'cron_reconcile_attribution'
+        and j.user_id = e.user_id
+        and j.status = 'completed'
+        and j.completed_at > now() - interval '50 minutes'
+    )
+  ), ins as (
+    insert into agent_jobs (user_id, task_kind, status, payload, dedupe_key)
+    select f.user_id,
+           'cron_reconcile_attribution',
+           'pending',
+           jsonb_build_object('limit', 200),
+           'reconcile-attribution:' || f.user_id
+    from fresh f
+    returning 1
+  )
+  select count(*)::int into queued from ins;
+
+  return queued;
+end;
+$$;
+
+comment on function public.enqueue_reconcile_attribution() is
+  'Hourly producer for cron_reconcile_attribution (:20). Enqueues one run per user holding sessions that are invisible to insights (project_id NULL, checkout-less project) OR self-contradictory (attributed but carrying a bare home-dir project_path — the pre-2026-08-26 normalizer shape). Does NOT repair anything itself: the evidence (transcript cwd, git anchors) lives on the machine that ran the session; the handler reads it and POSTs to POST /api/sessions and /api/sessions/:id/reimport.';
+
+-- ── 1b. Health view: agree with the producer ───────────────────────────────
+-- Three definitions of "the reconciler's universe" exist (producer, endpoint,
+-- this view); a shape one includes and another excludes is exactly how the
+-- home-path sessions stayed invisible for months. Same widening as above.
+
+create or replace view public.session_attribution_health as
+select
+  s.user_id,
+  count(*)::int as total_unattributed,
+  count(*) filter (
+    where s.started_at > now() - interval '90 days'
+      and s.external_session_id is not null
+      and (
+        s.project_path is null
+        or s.project_path !~ '^/(private/)?(tmp|var/folders)'
+      )
+  )::int as repairable_recent,
+  sum(s.event_count)::bigint as orphaned_events,
+  max(s.started_at) as newest_orphan
+from public.sessions s
+where s.project_id is null
+   or not exists (
+     select 1 from public.project_checkouts pc where pc.project_id = s.project_id
+   )
+   or s.project_path ~ '^/(Users|home)/[^/]+/?$'
+group by s.user_id;
+
+comment on view public.session_attribution_health is
+  'Per-user count of sessions invisible to the insights pipeline (unattributed, checkout-less project, or a self-contradictory bare home-dir project_path). repairable_recent is the subset cron_reconcile_attribution will attempt; a total that keeps climbing while repairable_recent stays near zero means the orphans are structurally unrepairable, not that the reconciler is failing.';
+
+-- ── 2. Conformance: metric + CHECK 6 ───────────────────────────────────────
+-- Full replace of 00209''s function body with one metric and one check added.
+-- (Producer-function churn is the known cost of logic-in-SQL; see the
+-- 2026-08-27 migration-treadmill review.)
+
+create or replace function public.suggestion_pipeline_conformance()
+returns table (check_id text, user_id uuid, detail text)
+language plpgsql
+security definer
+set search_path = public
+as $$
+begin
+  -- ── Snapshot metrics first, so the monotone checks below (and future ones)
+  -- have history even on days when every check is quiet. ────────────────────
+  insert into pipeline_conformance_metrics (user_id, metric, value)
+  select s.user_id, m.metric, m.value
+  from (
+    select distinct is2.user_id from instruction_suggestions is2
+    union
+    select distinct se.user_id from sessions se where se.started_at > now() - interval '90 days'
+  ) s
+  cross join lateral (
+    select 'stale_open_rows' as metric,
+           (select count(*) from instruction_suggestions x
+             where x.user_id = s.user_id and x.kind = 'add'
+               and x.accepted_at is null and x.dismissed_at is null
+               and x.is_stale) as value
+    union all
+    select 'undecided_add_rows',
+           (select count(*) from instruction_suggestions x
+             where x.user_id = s.user_id and x.kind = 'add'
+               and x.accepted_at is null and x.dismissed_at is null)
+    union all
+    select 'auto_accept_candidates',
+           (select count(*) from auto_accept_candidate_suggestions v
+             where v.user_id = s.user_id)
+    union all
+    -- The 0.5–0.79 band: emitted by the scorer (recommend.ts floors at 0.5),
+    -- below the adoption default (0.8). Feed-only by construction — counted so
+    -- "open suggestions" stops being one number over two populations (census
+    -- cause 1, 2026-08-27: 393 of 477 open skills sat in this band).
+    select 'feed_only_band_rows',
+           (select count(*) from instruction_suggestions x
+             join instructions i on i.id = x.instruction_id
+             where x.user_id = s.user_id and x.kind = 'add'
+               and x.accepted_at is null and x.dismissed_at is null
+               and i.type in ('instruction', 'skill')
+               and x.score < 0.8
+               and coalesce(i.frontmatter->>'source', '') <> 'insights')
+    union all
+    -- Undecided rows quiet for >90 days that the weekly prune can NEVER
+    -- collect, by design: they carry instruction_suggestion_events, the FK is
+    -- ON DELETE CASCADE, and those events are the only record the funnel's
+    -- numerator was ever zero (00180's comment names naive pruning as the
+    -- failure mode). Counted here instead of deleted: the census's 2026-08-27
+    -- "cause 4" proposed pruning them and was wrong — visibility is the fix
+    -- that does not destroy evidence.
+    select 'dormant_open_rows',
+           (select count(*) from instruction_suggestions x
+             where x.user_id = s.user_id and x.kind = 'add'
+               and x.accepted_at is null and x.dismissed_at is null
+               and x.generated_at < now() - interval '90 days'
+               and coalesce(
+                     (select max(ev.created_at) from instruction_suggestion_events ev
+                       where ev.suggestion_id = x.id),
+                     x.generated_at
+                   ) < now() - interval '90 days')
+    union all
+    -- Sessions attributed to a real project while carrying a bare home-dir
+    -- project_path — self-contradictory (a home dir is never a checkout), the
+    -- pre-2026-08-26 normalizer's signature. The reconciler repairs the ones
+    -- whose transcript survives; this count is the residue trending to zero.
+    select 'misattributed_session_paths',
+           (select count(*) from sessions x
+             where x.user_id = s.user_id
+               and x.project_id is not null
+               and x.project_path ~ '^/(Users|home)/[^/]+/?$'
+               and x.started_at > now() - interval '90 days')
+  ) m;
+
+  return query
+
+  -- ── CHECK 1: minted_on_forbidden_path ──────────────────────────────────────
+  -- Incident: census 2026-08-27 — 258 of 685 open proposals sat on paths the
+  -- writer is forbidden to touch (home dir, TMPDIR, worktrees, the dead
+  -- apps/cli). Fixed the same day by gating both mint sites on
+  -- assessMintablePath(). This check is that fix's regression alarm: any NEW
+  -- row on a non-canonical path means a mint site was added or the gate broke.
+  select 'minted_on_forbidden_path'::text,
+         s.user_id,
+         count(*) || ' suggestion(s) minted in the last 25h on non-canonical path(s), e.g. ' || min(s.project_path)
+  from instruction_suggestions s
+  where s.generated_at > now() - interval '25 hours'
+    and not exists (
+      select 1 from project_canonical_checkouts c where c.path = s.project_path
+    )
+  group by s.user_id
+
+  union all
+
+  -- ── CHECK 2: producer_silent_with_candidates ───────────────────────────────
+  -- Incident: gate 4 (00184→00197) — the DB producer's type clause matched zero
+  -- rows, pg_cron fired and SUCCEEDED at 05:00 for three days, enqueued
+  -- nothing, and no log line existed anywhere. Candidates older than 25h with
+  -- no job even CREATED in 25h cannot be a quiet night: the producer is hourly.
+  select 'producer_silent_with_candidates'::text,
+         v.user_id,
+         count(*) || ' candidate(s) (oldest ' ||
+           extract(day from now() - min(v.generated_at)) || 'd) but no auto-accept job created in 25h — the producer is not seeing them'
+  from auto_accept_candidate_suggestions v
+  where v.generated_at < now() - interval '25 hours'
+    and not exists (
+      select 1 from agent_jobs j
+      where j.user_id = v.user_id
+        and j.task_kind = 'cron_auto_accept_suggestions'
+        and j.created_at > now() - interval '25 hours'
+    )
+  group by v.user_id
+
+  union all
+
+  -- ── CHECK 3: endpoint_refuses_everything ───────────────────────────────────
+  -- Incident: gates 1–4 (#372, 2026-08-16..19) — the producer queued jobs, the
+  -- worker ran them, the ENDPOINT refused every candidate on a clause the
+  -- producer didn't have, and four days of `nothing-eligible` looked like four
+  -- quiet nights. Signature: jobs completing against a standing candidate set
+  -- while NOTHING moves — no acceptance, no refusal event. A healthy run
+  -- always moves one of those; a placeholder-refusal loop that repeats forever
+  -- without logging also lands here, and deserves to.
+  select 'endpoint_refuses_everything'::text,
+         v.user_id,
+         count(distinct v.suggestion_id) ||
+           ' candidate(s) standing >48h while auto-accept jobs completed — zero adoptions, zero refusal events. The producer and the endpoint disagree about eligibility.'
+  from auto_accept_candidate_suggestions v
+  where v.generated_at < now() - interval '48 hours'
+    and exists (
+      select 1 from agent_jobs j
+      where j.user_id = v.user_id
+        and j.task_kind = 'cron_auto_accept_suggestions'
+        and j.status = 'completed'
+        and j.updated_at > now() - interval '48 hours'
+    )
+    and not exists (
+      select 1 from instruction_suggestions a
+      where a.user_id = v.user_id
+        and a.accepted_at > now() - interval '48 hours'
+    )
+    and not exists (
+      select 1 from instruction_suggestion_events ev
+      join instruction_suggestions es on es.id = ev.suggestion_id
+      where es.user_id = v.user_id
+        and ev.event_type in ('redundant', 'partial_overlap', 'unresolvable_reference')
+        and ev.created_at > now() - interval '48 hours'
+    )
+  group by v.user_id
+
+  union all
+
+  -- ── CHECK 4: stale_flag_only_grows ─────────────────────────────────────────
+  -- Incident: gate 7 (2026-08-24) — is_stale was set by the mark-stale cron and
+  -- NOTHING ever cleared it; 51 adoption-grade proposals went invisible, and
+  -- one user's whole skill lane was structurally dead for weeks. A one-way flag
+  -- is invisible at any instant; over days it is a staircase. Fires when the
+  -- last 8 daily samples are all positive, never decrease, and end higher than
+  -- they started.
+  select 'stale_flag_only_grows'::text,
+         g.user_id,
+         'stale-flagged open rows grew ' || g.first_value || ' → ' || g.last_value ||
+           ' over ' || g.samples || ' daily samples with no decrease — nothing is un-flagging them'
+  from (
+    select m.user_id,
+           count(*) as samples,
+           (array_agg(m.value order by m.run_at))[1] as first_value,
+           (array_agg(m.value order by m.run_at desc))[1] as last_value,
+           bool_and(m.value > 0) as all_positive,
+           -- Non-decreasing across the window: max of pairwise drops is 0.
+           coalesce(max(m.drop), 0) = 0 as never_decreased
+    from (
+      select mm.user_id, mm.run_at, mm.value,
+             greatest(lag(mm.value) over (partition by mm.user_id order by mm.run_at) - mm.value, 0) as drop
+      from pipeline_conformance_metrics mm
+      where mm.metric = 'stale_open_rows'
+        and mm.run_at > now() - interval '8 days'
+    ) m
+    group by m.user_id
+  ) g
+  where g.samples >= 8 and g.all_positive and g.never_decreased and g.last_value > g.first_value
+
+  union all
+
+  -- ── CHECK 5: surface_budget_spent_on_unadoptable ───────────────────────────
+  -- Incident: gates 5/6 and census cause 2 — ~840 feature/hook/mcp pitches per
+  -- 30 days entered the SessionStart feed, burned their five-ask surface budget
+  -- on an audience that cannot act on them, and converted into permanent
+  -- silence-declines. Fixed 2026-08-27 by excluding non-adoptable types from
+  -- the session-start render set (feed.ts). Any surfaced event on such a row
+  -- after that is the filter regressing.
+  select 'surface_budget_spent_on_unadoptable'::text,
+         s.user_id,
+         count(distinct ev.suggestion_id) ||
+           ' non-adoptable proposal(s) (feature/hook/mcp/…) surfaced into sessions in the last 7d — they burn budget for an audience that cannot act'
+  from instruction_suggestion_events ev
+  join instruction_suggestions s on s.id = ev.suggestion_id
+  join instructions i on i.id = s.instruction_id
+  where ev.event_type in ('surfaced', 'surfaced_with_content')
+    and ev.created_at > now() - interval '7 days'
+    and s.kind = 'add'
+    and i.type not in ('instruction', 'skill')
+  group by s.user_id
+
+  union all
+
+  -- ── CHECK 6: session_capture_misattributed ─────────────────────────────────
+  -- Incident: 2026-08-27 — Thrakopontia's only session carried
+  -- project_path='/Users/nickyeager' (the pre-08-26 normalizer rewrote it) and
+  -- froze at 188 events while its transcript grew for three days, so the
+  -- project produced zero suggestions and the only symptom was an empty VS
+  -- Code panel. A RECENT session in this shape means either the normalizer
+  -- guard regressed (new junk being minted) or the reconciler is not running
+  -- for this user (worker off) — both actionable. Rows older than 7 days sit
+  -- in the misattributed_session_paths metric instead: their transcripts are
+  -- likely pruned, and a check that can never clear is a permanent red light
+  -- nobody reads.
+  select 'session_capture_misattributed'::text,
+         x.user_id,
+         count(*) || ' session(s) active in the last 7d attributed to a project while carrying a bare home-directory project_path — normalizer regression, or the reconciler is not repairing them (worker offline / transcript gone)'
+  from sessions x
+  where x.project_id is not null
+    and x.project_path ~ '^/(Users|home)/[^/]+/?$'
+    and x.started_at > now() - interval '7 days'
+  group by x.user_id;
+end;
+$$;
+
+comment on function public.suggestion_pipeline_conformance() is
+  'Daily conformance sweep over the suggestion/promotion pipeline. Each check encodes the observable signature of a dated incident (gate 4 silent producer, #372 producer/endpoint drift, gate 7 one-way staleness, census causes 2 and 3, the 2026-08-27 misattributed-session-path capture defect). Detection only — never mutates pipeline state. Findings land as one consolidated notification per user (pattern: 00147).';
+
+-- ── 3. Delete the laundering vector ────────────────────────────────────────
+-- A bare-home project_checkouts row makes resolveProjectIdForPath attribute
+-- every genuine home-dir session to whatever project the residue points at.
+-- Zero rows exist on the cloud DB at authoring time (the API-side guard has
+-- held since it shipped) — this is the backstop against rows minted by older
+-- API builds (local-mode installs) that predate the guard.
+delete from public.project_checkouts
+where path ~ '^/(Users|home)/[^/]+/?$';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulemetric/local",
-  "version": "0.12.3",
+  "version": "0.12.5",
   "description": "RuleMetric local-mode runtime: bundled API server, web dashboard, and database migrations for fully local (zero cloud contact) deployments. Installed on demand by `rulemetric local up` — not meant to be used directly.",
   "type": "module",
   "exports": {
@@ -28,7 +28,7 @@
     "postgres": "^3.4.0",
     "resend": "^4.0.0",
     "zod": "^3.24.0",
-    "@rulemetric/skills-registry": "0.12.3"
+    "@rulemetric/skills-registry": "0.12.5"
   },
   "devDependencies": {
     "esbuild": "^0.25.0",