Session continuity

​

What was already tried

​

But the curated path has a measured hole

​

What the misreporting evidence actually shows

​

Hook mechanics

1. A debrief cannot run at SessionEnd. By then there is nobody to instruct. That slot now runs 3ngram-hook close — one natural-key POST, no model (cmd/3ngram-hook/close.go); 3ngram-hook sync remains the deliberate no-op it always was (cmd/3ngram-hook/sync.go) and is no longer registered there. Neither slot can be upgraded into a triage. Codex states this structurally: SessionEnd is the only event with no output schema generated for it at all. Do not rely on SessionEnd for correctness: a killed terminal, crash, or failed POST leaves the row open. Layer 1 uses a lease, not SessionEnd, as the liveness signal.
2. Stop is a per-turn checkpoint, not a reliable closer. It does not fire on user interrupt. Claude documents background tasks and scheduled wakeups the current hook ignores. Treat it as an incremental nudge. The closer is a worker (layer 5).

​

Both harnesses support a blocking Stop, with mostly the same envelope

​

Settled architecture

1. session_id is known at Stop after the turn’s writes. Current remember / revise / resolve inputs are .strict() and carry no session field (packages/schema/src/write.ts). The runtime role can INSERT memory_events but cannot UPDATE them, so the hook cannot retrofit provenance onto rows already written.
2. Briefing is a read. GET /api/v1/briefing writes no audit row. Completing an old commitment via resolve is a write; being shown one is not.
3. memory_events cannot hold a session marker. Every row needs a real memory_id and an event_kind in the existing CHECK (create|revise|supersede|resolve|unresolve|archive|import|embed_failed).
4. A cursor sampled at SessionEnd sits after Session A’s writes, so a naive “since close” delta omits exactly the work that should hand off.
5. Stop is not a session boundary. The first qualifying turn is not “the session ended”, and marking triage complete before the model writes (or failing to absorb those writes) is a correctness bug either way.

​

Layer 1 — agent_sessions

agent_sessions (
  id                   uuid pk,              -- opaque sessionRunId handed to writes
  user_id              uuid not null,
  agent                text not null,        -- claude-code | codex | …
  session_id           text not null,        -- harness conversation id (reused on resume)
  source               text not null,        -- startup | resume   (compact is a no-op, never stored)
  project              text null,
  scope                text null,
  selector             jsonb not null,       -- effective briefing selector (kind + axes)
  opened_at            timestamptz not null,
  closed_at            timestamptz null,
  last_seen_at         timestamptz not null, -- lease heartbeat
  activation_epoch     int not null,         -- incremented on startup/resume/resurrect/erasure; closer fence, not SessionEnd
  triage_status        text not null,        -- idle | pending | completed | expired | overflowed (terminal)
  triage_attempt_id    uuid null,
  triage_armed_at      timestamptz null,     -- when the current attempt was armed; the age guard on the `pending` decline. NULL = unknown (pre-guard rows) = finalize
  triage_attempt_log   jsonb not null default '[]', -- the INTERACTIVE nudge history (issue #203): one {attemptId, armedAt, finalizedAt?, outcome?} per armed attempt, bounded (oldest dropped); closer claims are not logged. Ids, instants and outcome words only
  triage_attempt_count int not null default 0, -- true total ever armed, so a trimmed log is detectable
  last_triaged_event_ids jsonb not null default '[]', -- event ids ACCOUNTED FOR by triage: all ids visible at the last complete/expire, and the ids visible when the current attempt began — never a since-attempt-begin slice
  briefing_delivered_at timestamptz null,    -- when a briefing was shown; NOT a change-feed cursor
  briefed_memories     jsonb not null default '[]', -- [{id, topic, status}] bounded, not bare UUIDs
  last_message_excerpt text null,            -- bounded; closer input; cleared only after closer consumes; TTL sweep leftovers
  needs_look           boolean not null default false, -- closer scan discriminator: this run may hold an event outside the watermark; set by an attach onto a completed run, recomputed by every watermark stamp
  unique (user_id, agent, session_id)
)

​

SessionStart

​

Lease

• the claim itself (fenced at the epoch observed at step 1) — a pass whose epoch already moved before it claims never runs at all;
• the pre-gateway check, immediately before dispatch — this one only NARROWS the window rather than closing it: it is a read, not a lock, adjacent to the dispatch with no awaited work between them, but not serialized against the erasure commit. The claim is a fence, not an exclusive lease (session-closer.ts, claimSessionTriage’s own doc), so more than one of the account’s runs can be claimed and mid-pass at once — one racing dispatch per concurrently-executing closer pass, bounded by worker concurrency (one job at a time per replica today, the BullMQ Worker default apps/worker/src/queues.ts does not override) times however many replicas are running, not a single absolute request account-wide. Each one that does dispatch is on the wire for up to the gateway’s request timeout (30s default) before it completes — disclosed, not hidden, and not an absolute ”≤ timeout” guarantee (see the fence enumeration below for why closing it fully would mean a lock across the network call, which the design rejects by contract);
• each resolve write itself — this one CLOSES its window rather than narrowing it: transitionCommitment locks the commitment row before reading the run’s current epoch in a fresh statement, so a resolve racing an in-flight erasure either happens strictly before it (the lock-holder wins and writes legitimately) or is rejected with no write at all (erasure holds the lock first, the fresh read after the wait sees the bump);
• the final write-back, fenced on epoch AND attempt token — all-or-nothing.

​

Last-consumed cursor — deferred

• every SessionStart startup delivers today’s full bounded live-state briefing (mode=full: commitments, blockers, overdue, stale, recent decisions, preferences)
• an episodic “what this run wrote” section may sit beside that snapshot, never instead of it — an external gate clearing creates no memory event, and a delta-only briefing would hide the item that needs rechecking

​

PreCompact and Stop excerpt

​

Layer 2 — write-time provenance

nativeRememberInputSchema = rememberWithFactsInputSchema.safeExtend({
  sessionRunId: uuid.optional()
})

1. The caller may pass only an opaque sessionRunId as a native-only field. The server resolves it to a tenant-owned agent_sessions row. Session provenance (agent on the row) is derived server-side; a client-supplied provenance agent is rejected. project on remember / revise is the memory facet — the debrief prompt requires it — and is validated as today. Rejection of client-supplied fields applies to provenance-payload keys, not to the memory body. The memory write and the attachment are not the same decision. Another tenant’s run id (or a syntactically valid id that is not ours) fails the write — that is a cross-tenant probe. An explicitly closed row of this tenant: the write succeeds with payload unset. A stale-lease or implicitly closed row of this tenant: treat as implicit close, resurrect, then attach, in one transaction (see Lease). Bookkeeping going stale must not destroy curated writes, and must not silently drop attribution because a sweeper has not run yet.
2. Transports copy, they do not invent. MCP writes stay user_mcp; REST writes stay user_api. Session provenance is payload, not actor_kind. Reintroducing capture_hook is forbidden (migration 0010).
3. There is no MCP adapter the hook owns. 3ngram-hook is a separate SessionStart/Stop process; tool calls go client → /mcp directly. Attribution on the hooked path is best-effort and model-mediated: SessionStart injects the sessionRunId plus instructions to pass it on writes. Concurrent hooked sessions and agents that omit the field fall through to (4). Do not claim the hooked path always sends the id. The Stop hook heartbeats unconditionally, nudge or no nudge, so the lease stays fresh during completed turns and last_assistant_message is snapshotted every turn — the layer-4 triage is additive on top of that call, never a replacement for it.
4. Single-open-session default is the floor (vanilla MCP and hooked sessions that omitted the id). If the write omits sessionRunId and the tenant has exactly one leased-open row for that project, the write path MAY attach it. Zero or many → leave payload unset. Time-window guesses are out; they collide. Serialize that decision with a tenant/project advisory lock (the same genus as auth_resend_email_verification). FOR SHARE on the existing row does not block a concurrent INSERT of a different session — uniqueness is on (user_id, agent, session_id), not project — so it cannot prevent the phantom. Zero or many at commit → leave payload unset.

sessionProvenancePayloadSchema = { sessionRunId: uuid }.strict()

CREATE INDEX memory_events_session_idx
  ON memory_events (user_id, ((payload->>'sessionRunId')), id)
  WHERE payload->>'sessionRunId' IS NOT NULL;

​

Layer 3 — typed provenance read

GET /api/v1/agent-sessions/{sessionRunId}/events?cursor&limit
  -> { items: [{ id, memoryId, eventKind, actorKind, sessionRunId, createdAt }],
       nextCursor?, truncated }

​

Layer 4 — Stop is a nudge

​

Pending vs complete

Stop(stop_hook_active=false, triage_status=idle)
  → persist triage_status=pending (idempotent attempt id)
  → last_triaged_event_ids = event ids visible NOW   // the begin stamp
  → inject prompt
        ↓
  model writes (ordinary MCP, actor user_mcp)
        ↓
Stop(stop_hook_active=true)  OR  numeric self-cap hit
  → since_begin = event ids for this run since attempt begin
  → visible = all event ids for this run now (uuidv7 order, per-run ceiling)
  → last_triaged_event_ids = visible   // cumulative, not since_begin
  → if visible truncated: triage_status=overflowed   // terminal; closer does not retry
  → else if since_begin is empty: triage_status=expired   // closer-eligible
  → else: triage_status=completed

​

Debounce

​

Who is registered

​

Layer 5 — closer worker

1. at claim time — a run resurrected before the pass starts is never touched;
2. after the budget reservation, immediately before the gateway call (issue #185) — the last point before the excerpt and briefed topics leave the process at all, so this is what actually stops a stale send rather than merely stopping the pass from acting on the reply. Checked AFTER reserving, not before: the reservation takes a per-user advisory lock that can block behind another in-flight metered call for that user, and checking before it would let that wait inflate the residual below past the gateway’s own timeout;
3. before each resolve — a cheap read in its OWN transaction, so a resurrection during a slow generation stops the batch at the next candidate rather than at the end;
4. on the resolve write itself (issue #185) — transitionCommitment locks the commitment row (FOR UPDATE) BEFORE reading the run’s epoch, in a separate, freshly-snapshotted statement, and aborts on a mismatch before ever attempting the write. The lock is what makes the read trustworthy: an epoch check folded into the write’s own WHERE (an EXISTS(...) against agent_sessions) is NOT equivalent and does not work — a sub-SELECT inside a blocked-then-woken UPDATE’s WHERE still runs under that statement’s ORIGINAL snapshot even though Postgres re-checks the UPDATE’s own target row fresh (EvalPlanQual), so it can still read a pre-erasure epoch after erasure has already committed. Locking first and reading second closes that;
5. on the final write-back, together with the attempt token — the bookkeeping (terminal status, watermark, excerpt clear) is all-or-nothing.

• the session row (selector, briefed_memories, bounded last_message_excerpt)
• listSessionEvents(sessionRunId) (paginated; honor truncated)
• a live read of each resolve target
• the same debrief registrar for what to look for, not as a remember script

​

Layer 6 — SessionEnd is close, not capture

​

REST surface (hook-facing, API-key)

​

Cost to the tool budget: zero tools, not zero surface

​

Relation to threads and reconsolidation

​

Harness coverage

​

Explicitly not proposed

​

Plan

• positive improvement on commitment recall versus the 0% baseline (a closer that captures nothing still scores 26%/0%/zero-spurious and must not ship default-on)
• overall recall strictly above 26% or a pre-registered statistical improvement floor
• spurious / duplicate rate near the curated path’s zero
• extra-turn cost and ignore-rate of the nudge, measured
• attribution coverage, repeated-trigger rate, hook latency, corpus growth

​

Open questions

• Debounce thresholds (step 7). Settled at implementation (7a): SESSION_TRIAGE_MIN_TURNS defaults to 3 and SESSION_TRIAGE_MIN_ELAPSED_MINUTES to 10, and the third disjunct — an untriaged provenance event — has no knob because it is a fact about the run rather than a threshold. SESSION_TRIAGE_MIN_ATTEMPT_AGE_SECONDS (30) was added later, for the age guard on the pending decline, not for the debounce. Both matrices are pinned in packages/db/test/session-triage.test.ts. The lease is settled at 24h, with a 1h sweep grace on top: the lease already covers the overnight gap, so the grace only debounces the instant of expiry — and being non-zero is what keeps a swept closed_at outside the explicit-close window, so a swept row still resurrects.
• Closer actor kind. Settled: worker (layer 5).
• Evidence provenance. Corpus-damage numbers come from the engram-era Python implementation, migrated into this corpus.
• Change-feed. Replayable per-selector cursor, at-least-once, consume-time advance. Successor of briefing_delivered_at, not a substitute for the live snapshot. Not this epic.