@unpolarize/code-sessions 0.1.0 → 0.3.0

package/src/fork.test.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import type { Turn } from '@unpolarize/code-sessions-schema';
+import { forkSession } from './fork';
+import { envelopeFile, sessionDir, turnFile } from './store/paths';
+import { rebuildEnvelope, readTurns, writeTurnFile } from './store/writer';
+import { makeConfig, withTempDir } from './test/tmp';
+
+function turn(i: number, role: Turn['role'], text: string): Turn {
+  return {
+    schema: 'session-store/turn@1',
+    session_id: 'src',
+    host: 'h',
+    agent: 'claude-code',
+    turn_index: i,
+    ts: `2026-06-20T08:0${i}:00Z`,
+    role,
+    text,
+    tool_calls: [],
+    usage: { input_tokens: 100, output_tokens: 10, cache_read_tokens: 0, cache_write_tokens: 0 },
+    scrubbed: false,
+    raw_ref: null,
+  };
+}
+
+function seed(store: string): void {
+  const dir = sessionDir(store, 'test-host', '2026-06', 'src');
+  writeTurnFile(dir, turn(0, 'user', 'start the feature'));
+  writeTurnFile(dir, turn(1, 'assistant', 'working on it'));
+  writeTurnFile(dir, turn(2, 'user', 'change of plan'));
+  writeTurnFile(dir, turn(3, 'assistant', 'ok redoing'));
+  rebuildEnvelope(store, 'test-host', '2026-06', 'src', { model: 'claude-opus-4-8', title: 'feature work' }, {
+    session_id: 'src',
+    host: 'test-host',
+    agent: 'claude-code',
+    native_uuid: 'src',
+  });
+}
+
+describe('forkSession', () => {
+  it('branches a session at a turn with lineage', () => {
+    withTempDir((store) => {
+      seed(store);
+      const cfg = makeConfig(store);
+      const res = forkSession(cfg, { sessionId: 'src', atTurn: 1, newSessionId: 'fork1' });
+      expect(res.newSessionId).toBe('fork1');
+      expect(res.turns).toBe(2); // turns 0 and 1 only
+      expect(res.forkedFrom).toEqual({ session_id: 'src', turn_index: 1 });
+
+      const dir = sessionDir(store, 'test-host', '2026-06', 'fork1');
+      expect(existsSync(turnFile(dir, 0))).toBe(true);
+      expect(existsSync(turnFile(dir, 1))).toBe(true);
+      expect(existsSync(turnFile(dir, 2))).toBe(false); // not copied
+
+      const forkTurns = readTurns(dir);
+      expect(forkTurns.every((t) => t.session_id === 'fork1')).toBe(true);
+
+      const env = JSON.parse(readFileSync(envelopeFile(dir), 'utf8'));
+      expect(env.forked_from).toEqual({ session_id: 'src', turn_index: 1 });
+      expect(env.title).toBe('fork: feature work');
+      expect(env.native_ref.format).toBe('fork');
+    });
+  });
+
+  it('can fork into a different agent', () => {
+    withTempDir((store) => {
+      seed(store);
+      const res = forkSession(makeConfig(store), { sessionId: 'src', atTurn: 0, agent: 'grok' });
+      const env = JSON.parse(readFileSync(envelopeFile(res.sessionDir), 'utf8'));
+      expect(env.agent).toBe('grok');
+      expect(res.turns).toBe(1);
+    });
+  });
+
+  it('throws for a missing session', () => {
+    withTempDir((store) => {
+      expect(() => forkSession(makeConfig(store), { sessionId: 'nope', atTurn: 0 })).toThrow(/not found/);
+    });
+  });
+});

package/src/fork.ts

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  SCHEMA_VERSIONS,
+  safeParseSession,
+  type SessionEnvelope,
+  type Turn,
+} from '@unpolarize/code-sessions-schema';
+import type { CodeSessionsConfig } from './config';
+import { computeEnvelope, readTurns, writeTurnFile } from './store/writer';
+import { envelopeFile, monthOf, sessionDir } from './store/paths';
+import { listSessionDirs } from './store/scan';
+
+export interface ForkResult {
+  newSessionId: string;
+  sessionDir: string;
+  turns: number;
+  forkedFrom: { session_id: string; turn_index: number };
+}
+
+function locateSession(storeDir: string, sessionId: string): { dir: string } | undefined {
+  const ref = listSessionDirs(storeDir).find((r) => r.sessionId === sessionId);
+  return ref ? { dir: ref.dir } : undefined;
+}
+
+function loadEnvelope(dir: string): SessionEnvelope | undefined {
+  const p = envelopeFile(dir);
+  if (!existsSync(p)) return undefined;
+  const parsed = safeParseSession(JSON.parse(readFileSync(p, 'utf8')));
+  return parsed.success ? parsed.data : undefined;
+}
+
+function writeJsonAtomic(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+/**
+ * Fork a session at a turn — "git for sessions". Copies turns [0..atTurn] of the
+ * source into a NEW session keyed on this host, stamped with `forked_from`. The
+ * new session can be resumed/continued in any agent from that branch point; all
+ * turns stay discoverable via the index.
+ */
+export function forkSession(
+  cfg: CodeSessionsConfig,
+  opts: { sessionId: string; atTurn: number; newSessionId?: string; agent?: SessionEnvelope['agent'] },
+): ForkResult {
+  const located = locateSession(cfg.storeDir, opts.sessionId);
+  if (!located) throw new Error(`session not found in store: ${opts.sessionId}`);
+  const srcEnv = loadEnvelope(located.dir);
+  const allTurns = readTurns(located.dir);
+  const prefix = allTurns.filter((t) => t.turn_index <= opts.atTurn);
+  if (prefix.length === 0) throw new Error(`no turns at or before index ${opts.atTurn}`);
+
+  const newId = opts.newSessionId ?? randomUUID();
+  const agent = opts.agent ?? srcEnv?.agent ?? 'claude-code';
+  const month = monthOf(srcEnv?.started_at ?? prefix[0]?.ts);
+  const dir = sessionDir(cfg.storeDir, cfg.host, month, newId);
+
+  const newTurns: Turn[] = prefix.map((t) => ({
+    ...t,
+    session_id: newId,
+    host: cfg.host,
+    agent,
+  }));
+  for (const t of newTurns) writeTurnFile(dir, t);
+
+  const env = computeEnvelope(
+    newTurns,
+    {
+      ...(srcEnv?.model ? { model: srcEnv.model } : {}),
+      ...(srcEnv?.project_path ? { project_path: srcEnv.project_path } : {}),
+      ...(srcEnv?.title ? { title: `fork: ${srcEnv.title}` } : {}),
+    },
+    { session_id: newId, host: cfg.host, agent, native_uuid: newId },
+  );
+  env.forked_from = { session_id: opts.sessionId, turn_index: opts.atTurn };
+  env.native_ref.format = 'fork';
+  writeJsonAtomic(envelopeFile(dir), env);
+
+  return {
+    newSessionId: newId,
+    sessionDir: dir,
+    turns: newTurns.length,
+    forkedFrom: env.forked_from,
+  };
+}

package/src/index.ts

@@ -17,5 +17,7 @@ export * from './insights/index';
 export * from './telemetry/index';
 export * from './adapters/index';
 export * from './index_store/index';
+export * from './skills/index';
+export * from './fork';
 export * from './hooks/install';
 export * from './hooks/shim';

package/src/index_store/db.test.ts

@@ -91,6 +91,31 @@ describe('SessionIndex', () => {
     }
   });
 
+  it('aggregates usage by agent, day, project, and top-cost', () => {
+    const idx = new SessionIndex(':memory:');
+    try {
+      idx.upsertSession(env('c1', 'claude-code', { totals: { input_tokens: 100, output_tokens: 20, cost_usd: 2 } }), {
+        ...src,
+        projects: ['foo'],
+      });
+      idx.upsertSession(env('g1', 'grok', { totals: { input_tokens: 50, output_tokens: 5, cost_usd: 0.5 } }), {
+        ...src,
+        source_path: '/s/g.json',
+        projects: ['foo', 'bar'],
+      });
+      const u = idx.usageSummary();
+      expect(u.totals.sessions).toBe(2);
+      expect(u.totals.cost_usd).toBe(2.5);
+      expect(u.byAgent['claude-code']!.cost_usd).toBe(2);
+      expect(u.byProject['foo']!.sessions).toBe(2);
+      expect(u.byProject['bar']!.sessions).toBe(1);
+      expect(u.byDay[0]!.day).toBe('2026-06-20');
+      expect(u.topByCost[0]!.session_id).toBe('c1'); // highest cost first
+    } finally {
+      idx.close();
+    }
+  });
+
   it('filters by agent and deletes sessions (cascade turns)', () => {
     const idx = new SessionIndex(':memory:');
     try {

package/src/index_store/db.ts

@@ -21,7 +21,7 @@ const { DatabaseSync } = nodeRequire('node:sqlite') as {
  * can share the model.
  */
 
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
 
 export interface SessionIndexRow {
   session_id: string;
@@ -39,15 +39,36 @@ export interface SessionIndexRow {
   title: string | null;
   labels: string[];
   topic: string | null;
+  intent: string | null;
+  projects: string[];
   source_path: string;
 }
 
+export interface UsageBucket {
+  sessions: number;
+  input_tokens: number;
+  output_tokens: number;
+  cost_usd: number;
+}
+
+export interface UsageSummary {
+  totals: { sessions: number; input_tokens: number; output_tokens: number; cost_usd: number };
+  byAgent: Record<string, UsageBucket>;
+  byDay: Array<{ day: string } & UsageBucket>;
+  byProject: Record<string, UsageBucket>;
+  topByCost: Array<{ session_id: string; agent: string; cost_usd: number; label: string }>;
+}
+
 function toMs(iso: string | undefined): number | null {
   if (!iso) return null;
   const v = Date.parse(iso);
   return Number.isNaN(v) ? null : v;
 }
 
+function round6(n: number): number {
+  return Math.round(n * 1e6) / 1e6;
+}
+
 export class SessionIndex {
   readonly db: DatabaseSyncT;
 
@@ -60,7 +81,8 @@ export class SessionIndex {
 
   private migrate(): void {
     const row = this.db.prepare('PRAGMA user_version').get() as { user_version: number };
-    if ((row?.user_version ?? 0) < 1) {
+    const cur = row?.user_version ?? 0;
+    if (cur < 1) {
       this.db.exec(`
         CREATE TABLE IF NOT EXISTS session (
           session_id TEXT PRIMARY KEY,
@@ -78,6 +100,8 @@ export class SessionIndex {
           title TEXT,
           labels_json TEXT NOT NULL DEFAULT '[]',
           topic TEXT,
+          intent TEXT,
+          projects_json TEXT NOT NULL DEFAULT '[]',
           source_path TEXT NOT NULL,
           mtime_ms INTEGER NOT NULL DEFAULT 0,
           size_bytes INTEGER NOT NULL DEFAULT 0,
@@ -101,13 +125,24 @@ export class SessionIndex {
         CREATE TABLE IF NOT EXISTS insight (
           session_id TEXT PRIMARY KEY REFERENCES session(session_id) ON DELETE CASCADE,
           topic TEXT,
+          intent TEXT,
           tags_json TEXT NOT NULL DEFAULT '[]',
+          projects_json TEXT NOT NULL DEFAULT '[]',
           signals_json TEXT NOT NULL DEFAULT '[]',
           provider TEXT,
           generated_at TEXT
         );
       `);
       this.db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    } else if (cur < 2) {
+      // additive v1 -> v2: intent + projects columns
+      this.db.exec(`
+        ALTER TABLE session ADD COLUMN intent TEXT;
+        ALTER TABLE session ADD COLUMN projects_json TEXT NOT NULL DEFAULT '[]';
+        ALTER TABLE insight ADD COLUMN intent TEXT;
+        ALTER TABLE insight ADD COLUMN projects_json TEXT NOT NULL DEFAULT '[]';
+        PRAGMA user_version = ${SCHEMA_VERSION};
+      `);
     }
   }
 
@@ -125,21 +160,30 @@ export class SessionIndex {
 
   upsertSession(
     env: SessionEnvelope,
-    src: { source_path: string; mtime_ms: number; size_bytes: number; indexed_at: number; topic?: string },
+    src: {
+      source_path: string;
+      mtime_ms: number;
+      size_bytes: number;
+      indexed_at: number;
+      topic?: string;
+      intent?: string;
+      projects?: string[];
+    },
   ): void {
     this.db
       .prepare(
         `INSERT INTO session (session_id, host, agent, project_path, model, started_at, ended_at,
            turn_count, tool_call_count, input_tokens, output_tokens, cost_usd, title, labels_json,
-           topic, source_path, mtime_ms, size_bytes, indexed_at)
-         VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+           topic, intent, projects_json, source_path, mtime_ms, size_bytes, indexed_at)
+         VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
          ON CONFLICT(session_id) DO UPDATE SET
            host=excluded.host, agent=excluded.agent, project_path=excluded.project_path,
            model=excluded.model, started_at=excluded.started_at, ended_at=excluded.ended_at,
            turn_count=excluded.turn_count, tool_call_count=excluded.tool_call_count,
            input_tokens=excluded.input_tokens, output_tokens=excluded.output_tokens,
            cost_usd=excluded.cost_usd, title=excluded.title, labels_json=excluded.labels_json,
-           topic=excluded.topic, source_path=excluded.source_path, mtime_ms=excluded.mtime_ms,
+           topic=excluded.topic, intent=excluded.intent, projects_json=excluded.projects_json,
+           source_path=excluded.source_path, mtime_ms=excluded.mtime_ms,
            size_bytes=excluded.size_bytes, indexed_at=excluded.indexed_at`,
       )
       .run(
@@ -158,6 +202,8 @@ export class SessionIndex {
         env.title ?? null,
         JSON.stringify(env.labels ?? []),
         src.topic ?? null,
+        src.intent ?? null,
+        JSON.stringify(src.projects ?? []),
         src.source_path,
         src.mtime_ms,
         src.size_bytes,
@@ -190,13 +236,15 @@ export class SessionIndex {
   upsertInsight(ins: Insights): void {
     this.db
       .prepare(
-        `INSERT OR REPLACE INTO insight (session_id, topic, tags_json, signals_json, provider, generated_at)
-         VALUES (?,?,?,?,?,?)`,
+        `INSERT OR REPLACE INTO insight (session_id, topic, intent, tags_json, projects_json, signals_json, provider, generated_at)
+         VALUES (?,?,?,?,?,?,?,?)`,
       )
       .run(
         ins.session_id,
         ins.topic ?? null,
+        ins.intent ?? null,
         JSON.stringify(ins.tags ?? []),
+        JSON.stringify(ins.projects ?? []),
         JSON.stringify(ins.signals ?? []),
         ins.provider,
         ins.generated_at,
@@ -226,6 +274,8 @@ export class SessionIndex {
       title: r.title ?? null,
       labels: safeJson(r.labels_json),
       topic: r.topic ?? null,
+      intent: r.intent ?? null,
+      projects: safeJson(r.projects_json),
       source_path: r.source_path,
     };
   }
@@ -258,6 +308,59 @@ export class SessionIndex {
     return (rows as any[]).map((r) => this.rowToIndex(r));
   }
 
+  /** Aggregated usage for a Usage panel: totals, by agent, by day, by project, top cost. */
+  usageSummary(opts: { days?: number; topN?: number } = {}): UsageSummary {
+    const rows = this.db
+      .prepare(
+        'SELECT session_id, agent, started_at, input_tokens, output_tokens, cost_usd, projects_json, topic, title FROM session',
+      )
+      .all() as any[];
+    const totals = { sessions: rows.length, input_tokens: 0, output_tokens: 0, cost_usd: 0 };
+    const byAgent: Record<string, UsageBucket> = {};
+    const byDay: Record<string, UsageBucket> = {};
+    const byProject: Record<string, UsageBucket> = {};
+    const add = (m: Record<string, UsageBucket>, key: string, r: any) => {
+      const b = (m[key] ??= { sessions: 0, input_tokens: 0, output_tokens: 0, cost_usd: 0 });
+      b.sessions++;
+      b.input_tokens += r.input_tokens;
+      b.output_tokens += r.output_tokens;
+      b.cost_usd += r.cost_usd;
+    };
+    for (const r of rows) {
+      totals.input_tokens += r.input_tokens;
+      totals.output_tokens += r.output_tokens;
+      totals.cost_usd += r.cost_usd;
+      add(byAgent, r.agent || 'unknown', r);
+      if (r.started_at) add(byDay, new Date(r.started_at).toISOString().slice(0, 10), r);
+      for (const p of safeJson(r.projects_json)) add(byProject, p, r);
+    }
+    totals.cost_usd = round6(totals.cost_usd);
+    for (const m of [byAgent, byDay, byProject]) for (const b of Object.values(m)) b.cost_usd = round6(b.cost_usd);
+
+    const days = opts.days ?? 30;
+    const recentDays = Object.entries(byDay)
+      .sort((a, b) => (a[0] < b[0] ? 1 : -1))
+      .slice(0, days)
+      .map(([day, b]) => ({ day, ...b }));
+    const topByCost = rows
+      .map((r) => ({
+        session_id: r.session_id,
+        agent: r.agent,
+        cost_usd: round6(r.cost_usd),
+        label: r.topic || r.title || r.session_id,
+      }))
+      .sort((a, b) => b.cost_usd - a.cost_usd)
+      .slice(0, opts.topN ?? 10);
+
+    return {
+      totals,
+      byAgent,
+      byDay: recentDays,
+      byProject,
+      topByCost,
+    };
+  }
+
   stats(): { sessions: number; turns: number; cost_usd: number; byAgent: Record<string, number> } {
     const s = this.db.prepare('SELECT COUNT(*) c, COALESCE(SUM(cost_usd),0) cost FROM session').get() as {
       c: number;

package/src/index_store/sync.ts

@@ -51,6 +51,8 @@ export function syncIndex(
       const env = parsed.data;
 
       let topic: string | undefined;
+      let intent: string | undefined;
+      let projects: string[] = [];
       const insPath = insightsFile(ref.dir);
       let insights = undefined;
       if (existsSync(insPath)) {
@@ -58,6 +60,8 @@ export function syncIndex(
         if (pi.success) {
           insights = pi.data;
           topic = pi.data.topic;
+          intent = pi.data.intent;
+          projects = pi.data.projects ?? [];
         }
       }
 
@@ -66,7 +70,9 @@ export function syncIndex(
         mtime_ms,
         size_bytes,
         indexed_at: now,
+        projects,
         ...(topic ? { topic } : {}),
+        ...(intent ? { intent } : {}),
       });
       index.replaceTurns(env.session_id, readTurns(ref.dir));
       if (insights) index.upsertInsight(insights);

package/src/insights/heuristics.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import type { Turn } from '@unpolarize/code-sessions-schema';
-import { deriveSignals, deriveTags, guessTopic } from './heuristics';
+import { deriveIntent, deriveProjects, deriveSignals, deriveTags, guessTopic } from './heuristics';
 
 function turn(i: number, over: Partial<Turn> = {}): Turn {
   return {
@@ -69,3 +69,25 @@ describe('guessTopic / deriveTags', () => {
     expect(tags.sort()).toEqual(['Edit', 'Read']);
   });
 });
+
+describe('deriveIntent', () => {
+  it('classifies intent from the first user prompt', () => {
+    expect(deriveIntent([turn(0, { role: 'user', text: 'fix the parser bug' })])).toBe('bugfix');
+    expect(deriveIntent([turn(0, { role: 'user', text: 'add a dark mode feature' })])).toBe('feature');
+    expect(deriveIntent([turn(0, { role: 'user', text: 'refactor the auth module' })])).toBe('refactor');
+    expect(deriveIntent([turn(0, { role: 'user', text: 'research the best vector db' })])).toBe('research');
+    expect(deriveIntent([turn(0, { role: 'user', text: 'xyzzy' })])).toBe('other');
+    expect(deriveIntent([])).toBeUndefined();
+  });
+});
+
+describe('deriveProjects', () => {
+  it('derives project ids from edited file paths', () => {
+    const projects = deriveProjects([
+      turn(0, { tool_calls: [{ name: 'Edit', input: { file_path: '/Users/x/projects/foo/a.ts' } }] }),
+      turn(1, { tool_calls: [{ name: 'Write', input: { file_path: '/Users/x/projects/ai/bar/b.ts' } }] }),
+      turn(2, { tool_calls: [{ name: 'Read', input: { path: '/Users/x/docs/notes.md' } }] }),
+    ]);
+    expect(projects).toEqual(['ai/bar', 'docs', 'foo']);
+  });
+});

package/src/insights/heuristics.ts

@@ -1,4 +1,4 @@
-import type { Signal, Turn } from '@unpolarize/code-sessions-schema';
+import type { Intent, Signal, Turn } from '@unpolarize/code-sessions-schema';
 
 /**
  * Deterministic, LLM-free signal derivation. Runs regardless of provider so the
@@ -104,3 +104,50 @@ export function deriveTags(turns: Turn[]): string[] {
   for (const t of turns) for (const c of t.tool_calls) tags.add(c.name);
   return [...tags].slice(0, 12);
 }
+
+/** Map an edited file path to a coarse project id (…/projects/<id>, …/docs → docs). */
+export function projectIdFromPath(p: string): string | null {
+  const segs = p.split('/').filter(Boolean);
+  const i = segs.indexOf('projects');
+  if (i >= 0 && segs[i + 1] === 'ai' && segs[i + 2]) return `ai/${segs[i + 2]}`;
+  if (i >= 0 && segs[i + 1]) return segs[i + 1]!;
+  if (segs.includes('docs')) return 'docs';
+  return null;
+}
+
+/** Projects the session touched, from Edit/Write/Read tool file paths. */
+export function deriveProjects(turns: Turn[]): string[] {
+  const set = new Set<string>();
+  for (const t of turns) {
+    for (const c of t.tool_calls) {
+      const fp = (c.input as { file_path?: string; path?: string } | undefined)?.file_path
+        ?? (c.input as { path?: string } | undefined)?.path;
+      if (typeof fp === 'string') {
+        const id = projectIdFromPath(fp);
+        if (id) set.add(id);
+      }
+    }
+  }
+  return [...set].sort().slice(0, 12);
+}
+
+const INTENT_PATTERNS: [Intent, RegExp][] = [
+  ['bugfix', /\b(fix|bug|broken|error|crash|regression|failing|stack ?trace)\b/i],
+  ['feature', /\b(add|implement|build|create|feature|support|introduce|new )\b/i],
+  ['refactor', /\b(refactor|clean ?up|simplify|rename|restructure|extract|dedupe)\b/i],
+  ['research', /\b(research|investigate|explore|compare|evaluate|find out|how (do|does|to)|why)\b/i],
+  ['docs', /\b(document|docs|readme|write[ -]?up|notes|comment)\b/i],
+  ['review', /\b(review|audit|critique|check|inspect)\b/i],
+  ['ops', /\b(deploy|release|publish|install|configure|ci\/?cd|pipeline|infra)\b/i],
+];
+
+/** Classify the session's intent from the first substantive user prompt. */
+export function deriveIntent(turns: Turn[]): Intent | undefined {
+  const firstUser = turns.find((t) => t.role === 'user' && t.text.trim().length > 0);
+  if (!firstUser) return undefined;
+  const text = firstUser.text;
+  for (const [intent, re] of INTENT_PATTERNS) {
+    if (re.test(text)) return intent;
+  }
+  return 'other';
+}

package/src/insights/labeler.test.ts

@@ -52,8 +52,11 @@ describe('labelSession', () => {
       expect(ins!.generated_at).toBe('2026-06-20T09:00:00Z');
       expect(existsSync(insightsFile(dir))).toBe(true);
 
+      expect(ins!.intent).toBe('bugfix');
+      expect(ins!.tags).toContain('Edit'); // tags live on the insights record
       const env = JSON.parse(readFileSync(envelopeFile(dir), 'utf8'));
-      expect(env.labels).toContain('Edit');
+      expect(env.labels).toContain('intent:bugfix'); // envelope labels = intent/topic/projects
+      expect(env.labels.some((l: string) => l.startsWith('intent:'))).toBe(true);
     });
   });
 

package/src/insights/labeler.ts

@@ -11,7 +11,7 @@ import type { CodeSessionsConfig } from '../config';
 import { envelopeFile, insightsFile } from '../store/paths';
 import { listSessionDirs } from '../store/scan';
 import { readTurns } from '../store/writer';
-import { deriveSignals, deriveTags, guessTopic } from './heuristics';
+import { deriveIntent, deriveProjects, deriveSignals, deriveTags, guessTopic } from './heuristics';
 import { FakeProvider, type LabelResult, type Provider } from './provider';
 import { LlmProvider, claudeRunner, grokRunner, ollamaRunner } from './llm';
 
@@ -73,7 +73,7 @@ export async function labelSession(
   if (turns.length === 0) return undefined;
 
   const heuristicSignals = deriveSignals(turns);
-  let provided: LabelResult = { tags: [], signals: [] };
+  let provided: LabelResult = { tags: [], projects: [], signals: [] };
   try {
     provided = await provider.label({ sessionId: identity.sessionId, host: identity.host, turns });
   } catch {
@@ -81,7 +81,9 @@ export async function labelSession(
   }
 
   const topic = provided.topic ?? guessTopic(turns);
+  const intent = provided.intent ?? deriveIntent(turns);
   const tags = [...new Set([...provided.tags, ...deriveTags(turns)])].slice(0, 16);
+  const projects = [...new Set([...provided.projects, ...deriveProjects(turns)])].slice(0, 16);
   const signals = dedupeSignals([...heuristicSignals, ...provided.signals]);
 
   const insights: Insights = {
@@ -91,17 +93,22 @@ export async function labelSession(
     generated_at: opts.now ?? new Date().toISOString(),
     provider: provider.name,
     tags,
+    projects,
     signals,
   };
   if (topic) insights.topic = topic;
+  if (intent) insights.intent = intent;
   if (provided.summary) insights.summary = provided.summary;
 
   writeJsonAtomic(insightsFile(sessionDir), insights);
-  updateEnvelopeLabels(sessionDir, topic, tags);
+  updateEnvelopeLabels(sessionDir, { topic, intent, projects });
   return insights;
 }
 
-function updateEnvelopeLabels(sessionDir: string, topic: string | undefined, tags: string[]): void {
+function updateEnvelopeLabels(
+  sessionDir: string,
+  l: { topic?: string; intent?: string; projects: string[] },
+): void {
   const path = envelopeFile(sessionDir);
   if (!existsSync(path)) return;
   let env: SessionEnvelope;
@@ -110,7 +117,13 @@ function updateEnvelopeLabels(sessionDir: string, topic: string | undefined, tag
   } catch {
     return;
   }
-  env.labels = [...new Set([...(topic ? [topic] : []), ...tags])].slice(0, 16);
+  env.labels = [
+    ...new Set([
+      ...(l.intent ? [`intent:${l.intent}`] : []),
+      ...(l.topic ? [l.topic] : []),
+      ...l.projects.map((p) => `project:${p}`),
+    ]),
+  ].slice(0, 16);
   writeJsonAtomic(path, env);
 }
 

package/src/insights/llm.test.ts

@@ -54,7 +54,7 @@ describe('parseLabelJson', () => {
   });
 
   it('returns empty on non-JSON', () => {
-    expect(parseLabelJson('no json here')).toEqual({ tags: [], signals: [] });
+    expect(parseLabelJson('no json here')).toEqual({ tags: [], projects: [], signals: [] });
   });
 });