parser: capture sessionKind and promptSource from Claude Code transcripts (#1253)

## What

Capture two Claude Code launch/prompt-provenance fields that the indexer
currently reads past and discards:

- **`sessionKind`** — session-level (e.g. `"bg"`). Present on
background/headless sessions, absent on interactive ones. Lands in a new
`session_kind` column on `sessions`.
- **`promptSource`** — per user turn (e.g. `"typed"`, `"queued"`,
`"system"`, `"sdk"`). Marks whether a turn was a human-typed prompt or a
queued/system/SDK-injected one. Lands in a new `prompt_source` column on
`messages`.

## Why

Both signals exist on essentially every current Claude Code transcript
but are thrown away at parse time, so the archive can't answer two
questions it otherwise has the data for: was a session interactive or
headless, and was a given prompt typed by a human or injected. This
mirrors the recently-added `entrypoint` capture — same shape of
information, same reason to keep it.

## How

The change follows the existing `entrypoint` / `agent_label` and
`source_type` / `is_sidechain` handling rather than inventing a new
pattern:

- `sessionKind` is treated as a session-identity field alongside
`entrypoint`: first-non-empty-wins across the file, wired into the
incremental identity-escalation check, and blanked by the Cowork and
Qoder parsers that reuse the Claude parse body (exactly as they blank
`entrypoint`).
- `promptSource` is treated as a per-message source column alongside
`source_type`/`is_sidechain`, including the retained-field whitelist in
`compactClaudeEntry` and the message token fingerprints the PG/DuckDB
push fast-paths compare against.

Both columns are `NOT NULL DEFAULT ''`, so transcripts that predate the
fields and other agents that never emit them read empty and are
otherwise untouched. A `dataVersion` bump (79) triggers the standard
reparse so existing Claude rows backfill both fields. Capture is
mirrored across the SQLite, Postgres, and DuckDB stores (mirror
`SchemaVersion` 9) and the artifact wire format, where the manifest
advances to v3 and message segments to v2: older artifacts still decode
with the fields empty, while pre-provenance peers park new artifacts
behind the existing future-version gate instead of silently dropping the
fields. The fields also round-trip through artifact import, re-enqueue a
published session's export when only `session_kind` changes, and count
toward the export preflight's message-byte bound.

## Scope / limitations

- Pure field capture — no counting, aggregation, health-signal, or
automation-classification logic is touched.
- `session_kind`/`prompt_source` backfill via the dataVersion-79
reparse; rows whose source files no longer exist stay empty.
- No new API/CLI surface or UI is added; the columns are available for
consumers that read the archive directly.

## Where to look

- `internal/parser/claude.go` — the capture site (`sessionKind` next to
`entrypoint`; `promptSource` next to `isSidechain`) and the
`compactClaudeEntry` retained-field whitelist.
- `internal/parser/claude_provider.go`, `provider.go`,
`internal/sync/engine.go` — incremental identity threading for
`sessionKind`.
- `internal/db/{schema.sql,db.go,sessions.go,messages.go}` — SQLite
columns, migrations, and read/write plumbing.
- `internal/postgres/*` and `internal/duckdb/*` — the mirrored columns
and fingerprints.

The source of truth for both fields is the Claude Code transcript
format, where `sessionKind` and `promptSource` appear as top-level keys
on session JSONL entries.

---------

Co-authored-by: Matthew Jacobs <mjacobs@apache.org>

Author: TweedBeetle

docs/internal/session-format-sources.md

@@ -103,6 +103,13 @@ Grok section and remove the explicit registry exception in the coverage test.
   in [#1238](https://github.com/kenn-io/agentsview/issues/1238): Claude Code
   for VS Code writes standalone `user` records wrapped in `ide_opened_file` or
   `ide_selection` tags for editor context rather than operator prompts.
+  Reverified 2026-07-24 against local CLI transcripts: current
+  transcripts carry two top-level launch/prompt-provenance keys that the
+  parser now captures — `sessionKind` (session-level, e.g. `"bg"`; present on
+  background/headless sessions and absent on interactive ones) and
+  `promptSource` (per user turn, e.g. `"typed"`, `"queued"`, `"system"`,
+  `"sdk"`). Neither key is documented upstream or covered by the codeburn
+  notes; the evidence remains local observation under `no-public-source`.
 
 ## OpenClaude (`openclaude`)
 

frontend/src/lib/api/generated/models/DbMessage.ts

@@ -97,10 +97,10 @@ func TestCanonicalManifestGolden(t *testing.T) {
 	require.NoError(t, err)
 
 	assert.Equal(t,
-		"{\"data_version\":99,\"generation\":3,\"native_session_id\":\"sess-1\",\"origin\":\"laptop-a1b2c3\",\"raw_source\":{\"hash\":\"raw123\",\"media_type\":\"application/jsonl\",\"path\":\"claude/session.jsonl\",\"size\":4096},\"segments\":[\"seg222\",\"seg111\"],\"session\":{\"agent\":\"claude\",\"compaction_count\":0,\"consecutive_failure_max\":0,\"created_at\":\"2026-06-14T01:02:03Z\",\"edit_churn_count\":0,\"ended_at\":\"2026-06-14T01:03:03Z\",\"ended_with_role\":\"\",\"final_failure_streak\":0,\"first_message\":\"hello\",\"has_peak_context_tokens\":false,\"has_total_output_tokens\":false,\"id\":\"sess-1\",\"is_automated\":false,\"machine\":\"laptop-a1b2c3\",\"message_count\":2,\"mid_task_compaction_count\":0,\"outcome\":\"\",\"outcome_confidence\":\"\",\"parent_session_id\":\"parent-1\",\"peak_context_tokens\":0,\"project\":\"alpha\",\"relationship_type\":\"subagent\",\"secret_leak_count\":0,\"started_at\":\"2026-06-14T01:02:03Z\",\"tool_failure_signal_count\":0,\"tool_retry_count\":0,\"total_output_tokens\":42,\"user_message_count\":1},\"session_has_context_data\":true,\"session_has_tool_calls\":true,\"session_name\":\"Fixture\",\"session_quality_signals\":{\"duplicate_prompt_count\":6,\"missing_success_criteria_count\":4,\"missing_verification_count\":5,\"no_code_context_count\":7,\"runaway_tool_loop_count\":1,\"short_prompt_count\":2,\"unstructured_start\":true,\"version\":3},\"usage_events\":[{\"cost\":{\"microdollars\":31250},\"cost_source\":\"fixture\",\"cost_status\":\"known\",\"dedup_key\":\"usage-1\",\"input_tokens\":11,\"message_ordinal\":2,\"model\":\"claude-test\",\"occurred_at\":\"2026-06-14T01:02:04Z\",\"output_tokens\":7,\"source\":\"fixture\"}],\"v\":2}\n",
+		"{\"data_version\":99,\"generation\":3,\"native_session_id\":\"sess-1\",\"origin\":\"laptop-a1b2c3\",\"raw_source\":{\"hash\":\"raw123\",\"media_type\":\"application/jsonl\",\"path\":\"claude/session.jsonl\",\"size\":4096},\"segments\":[\"seg222\",\"seg111\"],\"session\":{\"agent\":\"claude\",\"compaction_count\":0,\"consecutive_failure_max\":0,\"created_at\":\"2026-06-14T01:02:03Z\",\"edit_churn_count\":0,\"ended_at\":\"2026-06-14T01:03:03Z\",\"ended_with_role\":\"\",\"final_failure_streak\":0,\"first_message\":\"hello\",\"has_peak_context_tokens\":false,\"has_total_output_tokens\":false,\"id\":\"sess-1\",\"is_automated\":false,\"machine\":\"laptop-a1b2c3\",\"message_count\":2,\"mid_task_compaction_count\":0,\"outcome\":\"\",\"outcome_confidence\":\"\",\"parent_session_id\":\"parent-1\",\"peak_context_tokens\":0,\"project\":\"alpha\",\"relationship_type\":\"subagent\",\"secret_leak_count\":0,\"started_at\":\"2026-06-14T01:02:03Z\",\"tool_failure_signal_count\":0,\"tool_retry_count\":0,\"total_output_tokens\":42,\"user_message_count\":1},\"session_has_context_data\":true,\"session_has_tool_calls\":true,\"session_name\":\"Fixture\",\"session_quality_signals\":{\"duplicate_prompt_count\":6,\"missing_success_criteria_count\":4,\"missing_verification_count\":5,\"no_code_context_count\":7,\"runaway_tool_loop_count\":1,\"short_prompt_count\":2,\"unstructured_start\":true,\"version\":3},\"usage_events\":[{\"cost\":{\"microdollars\":31250},\"cost_source\":\"fixture\",\"cost_status\":\"known\",\"dedup_key\":\"usage-1\",\"input_tokens\":11,\"message_ordinal\":2,\"model\":\"claude-test\",\"occurred_at\":\"2026-06-14T01:02:04Z\",\"output_tokens\":7,\"source\":\"fixture\"}],\"v\":3}\n",
 		string(data),
 	)
-	assert.Equal(t, "d84a3987c40f800f23ea943ebd50c0910c64444e6ff4b64b6f8a68782f7a32d6", hashHex(data))
+	assert.Equal(t, "855d1a7ed086095582cc94136837bcb93d74f4ad0cf446b0a77177d1b31aba23", hashHex(data))
 }
 
 func TestDecodeManifestRejectsUnsupportedOlderVersion(t *testing.T) {
@@ -122,6 +122,37 @@ func TestDecodeManifestRejectsUnsupportedOlderVersion(t *testing.T) {
 	assert.Contains(t, err.Error(), "manifest has unsupported artifact version 1")
 }
 
+func TestDecodeManifestAcceptsPriorVersionWithoutSessionKind(t *testing.T) {
+	data := []byte(`{
+		"v": 2,
+		"origin": "laptop-a1b2c3",
+		"native_session_id": "sess-1",
+		"segments": [],
+		"session": {
+			"id": "sess-1",
+			"machine": "laptop-a1b2c3",
+			"agent": "claude",
+			"created_at": "2026-06-14T01:02:03Z"
+		}
+	}`)
+
+	decoded, err := decodeManifestWithLimits(data, productionArtifactLimits())
+	require.NoError(t, err)
+	assert.Equal(t, 2, decoded.Version)
+	assert.Empty(t, decoded.Session.SessionKind,
+		"v2 manifests predate session_kind and must decode with it empty")
+}
+
+func TestDecodeSegmentAcceptsPriorVersionWithoutPromptSource(t *testing.T) {
+	data := []byte("{\"content\":\"hello\",\"ordinal\":0,\"role\":\"user\",\"v\":1}\n")
+
+	msgs, err := decodeSegmentWithLimits(data, productionArtifactLimits())
+	require.NoError(t, err)
+	require.Len(t, msgs, 1)
+	assert.Empty(t, msgs[0].PromptSource,
+		"v1 segments predate prompt_source and must decode with it empty")
+}
+
 func TestCanonicalMessageSegmentGolden(t *testing.T) {
 	msgs := []db.Message{
 		{
@@ -177,13 +208,39 @@ func TestCanonicalMessageSegmentGolden(t *testing.T) {
 	require.NoError(t, err)
 
 	assert.Equal(t,
-		"{\"claude_message_id\":\"msg-1\",\"claude_request_id\":\"req-1\",\"content\":\"world\",\"content_length\":5,\"has_output_tokens\":true,\"has_tool_use\":true,\"model\":\"claude-test\",\"ordinal\":2,\"output_tokens\":2,\"role\":\"assistant\",\"source_parent_uuid\":\"uuid-parent\",\"source_subtype\":\"assistant\",\"source_type\":\"jsonl\",\"source_uuid\":\"uuid-msg-1\",\"timestamp\":\"2026-06-14T01:02:05Z\",\"token_usage\":{\"input\":1,\"output\":2},\"tool_calls\":[{\"call_index\":0,\"category\":\"file\",\"file_path\":\"README.md\",\"input_json\":\"{\\\"file_path\\\":\\\"README.md\\\"}\",\"result_content\":\"file content\",\"result_content_length\":12,\"result_events\":[{\"agent_id\":\"agent-1\",\"content\":\"done\",\"content_length\":4,\"event_index\":0,\"source\":\"tool_result\",\"status\":\"success\",\"subagent_session_id\":\"child-1\",\"timestamp\":\"2026-06-14T01:02:06Z\",\"tool_use_id\":\"tool-1\"}],\"subagent_session_id\":\"child-1\",\"tool_name\":\"Read\",\"tool_use_id\":\"tool-1\"}],\"v\":1}\n",
+		"{\"claude_message_id\":\"msg-1\",\"claude_request_id\":\"req-1\",\"content\":\"world\",\"content_length\":5,\"has_output_tokens\":true,\"has_tool_use\":true,\"model\":\"claude-test\",\"ordinal\":2,\"output_tokens\":2,\"role\":\"assistant\",\"source_parent_uuid\":\"uuid-parent\",\"source_subtype\":\"assistant\",\"source_type\":\"jsonl\",\"source_uuid\":\"uuid-msg-1\",\"timestamp\":\"2026-06-14T01:02:05Z\",\"token_usage\":{\"input\":1,\"output\":2},\"tool_calls\":[{\"call_index\":0,\"category\":\"file\",\"file_path\":\"README.md\",\"input_json\":\"{\\\"file_path\\\":\\\"README.md\\\"}\",\"result_content\":\"file content\",\"result_content_length\":12,\"result_events\":[{\"agent_id\":\"agent-1\",\"content\":\"done\",\"content_length\":4,\"event_index\":0,\"source\":\"tool_result\",\"status\":\"success\",\"subagent_session_id\":\"child-1\",\"timestamp\":\"2026-06-14T01:02:06Z\",\"tool_use_id\":\"tool-1\"}],\"subagent_session_id\":\"child-1\",\"tool_name\":\"Read\",\"tool_use_id\":\"tool-1\"}],\"v\":2}\n",
 		string(data),
 	)
 	assert.NotContains(t, string(data), `"id"`)
 	assert.NotContains(t, string(data), `"session_id"`)
 	assert.NotContains(t, string(data), `"message_id"`)
-	assert.Equal(t, "f46c1edbc77dab4eb15f43bcb3ce196243c784445b07e9135c223b5d58c6dea5", hashHex(data))
+	assert.Equal(t, "e45219604ab58bb9685ac3dfb0f5cc5e865705e29dc8a985ccebe1b748a6d396", hashHex(data))
+}
+
+func TestEncodeSegmentPreservesPromptSource(t *testing.T) {
+	msgs := []db.Message{
+		{
+			ID:            1,
+			SessionID:     "sess-1",
+			Ordinal:       1,
+			Role:          "user",
+			Content:       "hello",
+			SourceType:    "jsonl",
+			SourceSubtype: "user",
+			PromptSource:  "typed",
+		},
+	}
+
+	data, err := encodeSegment(msgs)
+	require.NoError(t, err)
+
+	var decoded segmentMessage
+	require.NoError(t, json.Unmarshal(data, &decoded))
+	assert.Equal(t, "typed", decoded.PromptSource)
+
+	restored := decoded.dbMessage()
+	assert.Equal(t, "typed", restored.PromptSource,
+		"import must carry prompt_source back into the db message")
 }
 
 func TestCanonicalMetadataEventGolden(t *testing.T) {

frontend/src/lib/api/generated/models/DbSession.ts

@@ -72,34 +72,34 @@ func TestReadVerifiedImportArtifactByteBoundaries(t *testing.T) {
 func TestFutureArtifactVersionErrorsIdentifyDependencyKind(t *testing.T) {
 	t.Run("manifest", func(t *testing.T) {
 		_, err := decodeManifestWithLimits(
-			[]byte(`{"origin":"contract-a1b2c3","v":3}`),
+			[]byte(`{"origin":"contract-a1b2c3","v":4}`),
 			productionArtifactLimits(),
 		)
 		require.ErrorIs(t, err, errFutureArtifactVersion)
 		var future *futureArtifactVersionError
 		require.ErrorAs(t, err, &future)
 		assert.Equal(t, Kind(KindManifests), future.Kind)
-		assert.Equal(t, 3, future.Version)
+		assert.Equal(t, 4, future.Version)
 	})
 
 	t.Run("segment", func(t *testing.T) {
 		_, err := decodeSegmentWithLimits(
-			[]byte("{\"content\":\"future\",\"ordinal\":0,\"role\":\"user\",\"v\":2}\n"),
+			[]byte("{\"content\":\"future\",\"ordinal\":0,\"role\":\"user\",\"v\":3}\n"),
 			productionArtifactLimits(),
 		)
 		require.ErrorIs(t, err, errFutureArtifactVersion)
 		var future *futureArtifactVersionError
 		require.ErrorAs(t, err, &future)
 		assert.Equal(t, Kind(KindSegments), future.Kind)
-		assert.Equal(t, 2, future.Version)
+		assert.Equal(t, 3, future.Version)
 	})
 }
 
 func TestFutureSegmentVersionPrecedesCurrentRecordLimit(t *testing.T) {
 	var body strings.Builder
 	for range productionArtifactLimits().segmentMessages + 1 {
 		body.WriteString(
-			"{\"content\":\"future\",\"ordinal\":0,\"role\":\"user\",\"v\":2}\n",
+			"{\"content\":\"future\",\"ordinal\":0,\"role\":\"user\",\"v\":3}\n",
 		)
 	}
 
@@ -110,7 +110,7 @@ func TestFutureSegmentVersionPrecedesCurrentRecordLimit(t *testing.T) {
 	var future *futureArtifactVersionError
 	require.ErrorAs(t, err, &future)
 	assert.Equal(t, Kind(KindSegments), future.Kind)
-	assert.Equal(t, 2, future.Version)
+	assert.Equal(t, 3, future.Version)
 }
 
 func TestCurrentSegmentRecordLimitPrecedesLaterRecordDecode(t *testing.T) {

frontend/src/lib/api/generated/models/DbSidebarSessionIndexRow.ts

@@ -159,7 +159,7 @@ func loadImportedSession(
 func validateImportedManifest(
 	m manifest, origin, gid string, limits artifactLimits,
 ) error {
-	if m.Version != manifestFormatVersion {
+	if m.Version < manifestMinDecodeVersion || m.Version > manifestFormatVersion {
 		return errors.New("manifest version is unsupported")
 	}
 	if m.Origin != origin {

internal/artifact/format_test.go

@@ -143,7 +143,7 @@ func TestLoadImportedSessionDefersOversizedFutureSegment(t *testing.T) {
 	var segment strings.Builder
 	for range productionArtifactLimits().segmentMessages + 1 {
 		segment.WriteString(
-			"{\"content\":\"future\",\"ordinal\":0,\"role\":\"user\",\"v\":2}\n",
+			"{\"content\":\"future\",\"ordinal\":0,\"role\":\"user\",\"v\":3}\n",
 		)
 	}
 	segmentHash := createHashedImportArtifact(
@@ -165,7 +165,7 @@ func TestLoadImportedSessionDefersOversizedFutureSegment(t *testing.T) {
 	var future *futureArtifactVersionError
 	require.ErrorAs(t, err, &future)
 	assert.Equal(t, Kind(KindSegments), future.Kind)
-	assert.Equal(t, 2, future.Version)
+	assert.Equal(t, 3, future.Version)
 }
 
 func TestLoadImportedSessionDefersMissingAndFutureDependencies(t *testing.T) {
@@ -191,7 +191,7 @@ func TestLoadImportedSessionDefersMissingAndFutureDependencies(t *testing.T) {
 		{
 			name: "future manifest",
 			prepare: func(t *testing.T, store ArtifactStore) string {
-				body := []byte(`{"origin":"contract-a1b2c3","v":3}`)
+				body := []byte(`{"origin":"contract-a1b2c3","v":4}`)
 				return createHashedImportArtifact(
 					t, store, KindManifests, ".json", body,
 				)
@@ -202,7 +202,7 @@ func TestLoadImportedSessionDefersMissingAndFutureDependencies(t *testing.T) {
 			name: "future segment",
 			prepare: func(t *testing.T, store ArtifactStore) string {
 				segment := []byte(
-					"{\"content\":\"future\",\"ordinal\":0,\"role\":\"user\",\"v\":2}\n",
+					"{\"content\":\"future\",\"ordinal\":0,\"role\":\"user\",\"v\":3}\n",
 				)
 				segmentHash := createHashedImportArtifact(
 					t, store, KindSegments, ".ndjson", segment,

internal/artifact/import_checkpoint_test.go

@@ -217,21 +217,22 @@ func TestStoreImportCoordinatorTracksIndependentFutureRequirements(t *testing.T)
 			prepare: func(t *testing.T, store ArtifactStore) string {
 				return createHashedImportArtifact(
 					t, store, KindManifests, ".json",
-					[]byte(`{"origin":"contract-a1b2c3","v":3}`),
+					[]byte(`{"origin":"contract-a1b2c3","v":4}`),
 				)
 			},
-			wantManifest: 3, wantSegment: messageSegmentFormatVersion,
+			wantManifest: manifestFormatVersion + 1,
+			wantSegment:  messageSegmentFormatVersion,
 			understood: db.ArtifactImportVersions{
 				Checkpoint: checkpointFormatVersion,
-				Manifest:   3,
+				Manifest:   manifestFormatVersion + 1,
 				Segment:    messageSegmentFormatVersion,
 			},
 		},
 		{
 			name: "future segment",
 			prepare: func(t *testing.T, store ArtifactStore) string {
 				segment := []byte(
-					"{\"content\":\"future\",\"ordinal\":0,\"role\":\"user\",\"v\":2}\n",
+					"{\"content\":\"future\",\"ordinal\":0,\"role\":\"user\",\"v\":3}\n",
 				)
 				segmentHash := createHashedImportArtifact(
 					t, store, KindSegments, ".ndjson", segment,
@@ -240,11 +241,12 @@ func TestStoreImportCoordinatorTracksIndependentFutureRequirements(t *testing.T)
 				m.Segments = []string{segmentHash}
 				return createImportTestManifest(t, store, m, false)
 			},
-			wantManifest: manifestFormatVersion, wantSegment: 2,
+			wantManifest: manifestFormatVersion,
+			wantSegment:  messageSegmentFormatVersion + 1,
 			understood: db.ArtifactImportVersions{
 				Checkpoint: checkpointFormatVersion,
 				Manifest:   manifestFormatVersion,
-				Segment:    2,
+				Segment:    messageSegmentFormatVersion + 1,
 			},
 		},
 	}
@@ -343,7 +345,7 @@ func TestStoreImportCoordinatorFinishesSupportedSessionsBeforeFutureGate(
 	sessionMap := map[string]string{
 		contractOrigin + "~000-future": createHashedImportArtifact(
 			t, store, KindManifests, ".json",
-			[]byte(`{"origin":"contract-a1b2c3","v":3}`),
+			[]byte(`{"origin":"contract-a1b2c3","v":4}`),
 		),
 	}
 	const supportedSessions = artifactImportDrainLimit + 1
@@ -405,15 +407,15 @@ func TestStoreImportCoordinatorFinishesSupportedSessionsBeforeFutureGate(
 		t.Context(),
 		db.ArtifactImportVersions{
 			Checkpoint: checkpointFormatVersion,
-			Manifest:   3,
+			Manifest:   manifestFormatVersion + 1,
 			Segment:    messageSegmentFormatVersion,
 		},
 		attempt,
 		10,
 	)
 	require.NoError(t, err)
 	require.Len(t, pending, 1)
-	assert.Equal(t, 3, pending[0].RequiredManifestVersion)
+	assert.Equal(t, manifestFormatVersion+1, pending[0].RequiredManifestVersion)
 }
 
 func TestStoreImportCoordinatorQuarantinesInvalidCheckpointAndContinues(

internal/artifact/import_session.go

@@ -16,6 +16,7 @@ type manifestSession struct {
 	Agent                string  `json:"agent"`
 	AgentLabel           string  `json:"agent_label,omitempty"`
 	Entrypoint           string  `json:"entrypoint,omitempty"`
+	SessionKind          string  `json:"session_kind,omitempty"`
 	FirstMessage         *string `json:"first_message"`
 	DisplayName          *string `json:"display_name,omitempty"`
 	StartedAt            *string `json:"started_at"`
@@ -95,6 +96,7 @@ func manifestSessionFromDB(s db.Session) manifestSession {
 		Agent:                s.Agent,
 		AgentLabel:           s.AgentLabel,
 		Entrypoint:           s.Entrypoint,
+		SessionKind:          s.SessionKind,
 		FirstMessage:         s.FirstMessage,
 		DisplayName:          s.DisplayName,
 		StartedAt:            s.StartedAt,
@@ -155,6 +157,7 @@ func (m manifestSession) dbSession() db.Session {
 		Agent:                m.Agent,
 		AgentLabel:           m.AgentLabel,
 		Entrypoint:           m.Entrypoint,
+		SessionKind:          m.SessionKind,
 		FirstMessage:         m.FirstMessage,
 		DisplayName:          m.DisplayName,
 		StartedAt:            m.StartedAt,