feat(levelcode): auto-archive stale sessions at 30 days + a Pin toggle

The "keep the magic" pair from the sessions design (§4.9): the working set
fades on its own, and you protect what matters. Auto-archive quietly retires
sessions you haven't touched in 30 days; Pin exempts a session from that (and
floats it above the time buckets, past the 30-item cap).

- sessions.js: autoArchiveStale({ days, nowMs }) archives every active,
  non-pinned, non-live session older than the cutoff — append-only (a label
  event each), NEVER deletes, pinned exempt, idempotent. Exported alongside the
  existing setPinned.
- extension.js: handleSessionAction gains 'pin' (toggles setPinned + refreshes
  both surfaces); activate runs the sweep once on startup (deferred, guarded,
  off when the setting is 0) and refreshes the list if anything faded.
- media/chat.html, media/sessionsView.html: a Pin/Unpin button in the card's
  hover actions (byte-identical in the shared SESSIONS-PURE block — drift test
  green); the star already marked pinned at rest.
- package.json: sessions.autoArchiveDays (default 30, 0 = off).
- tests: +1 sessions (sweep: stale faded, pinned/recent exempt, idempotent),
  +1 sessionsUi (Pin toggle on the card + housekeeping wiring), and the rich/
  rest card tests now assert Pin/Unpin. Full suite 30 files green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ndemianc

extensions/levelcode-ai/extension.js

@@ -704,6 +704,7 @@ async function handleSessionAction(action, id) {
 		if (action === 'resume') { await resumeSession(id); return; }
 		if (action === 'done') { m.archive(id); refreshSessions(); return; }
 		if (action === 'delete') { m.trash(id); refreshSessions(); return; }
+		if (action === 'pin') { const cur = (m.list().find((e) => e.id === id) || {}).pinned; m.setPinned(id, !cur); refreshSessions(); return; }
 		if (action === 'rename') {
 			const cur = (m.list().find((e) => e.id === id) || {}).title || '';
 			const title = await vscode.window.showInputBox({ prompt: 'Rename this session', value: cur, validateInput: (v) => (v && v.trim() ? null : 'Enter a name') });
@@ -2237,6 +2238,16 @@ function activate(context) {
 		fastCompletionModel: catalog.fastCompletionModel
 	});
 
+	// Sessions housekeeping: fade sessions untouched for a while out of the working set (§4.9 — auto-archive
+	// at 30 days, pinned exempt, NEVER deletes). Deferred + guarded so it never slows or breaks activation;
+	// off when levelcode.ai.sessions.autoArchiveDays is 0.
+	setTimeout(() => {
+		try {
+			const days = aiConfig().get('sessions.autoArchiveDays', 30);
+			if (days > 0) { const mgr = sessionsManager(); if (mgr) { const nArch = mgr.autoArchiveStale({ days }); if (nArch) { dbg('sessions.autoArchive', { archived: nArch, days }); refreshSessions(); } } }
+		} catch (e) { /* housekeeping is best-effort */ }
+	}, 1500);
+
 	// AI-first: reveal the chat (in the secondary side bar) on EVERY launch until the user has actually
 	// engaged (sent their first message). This makes sure new users always see it, instead of it only
 	// showing once. Once they've sent a message (handleSend sets the flag) we stop forcing it and defer

extensions/levelcode-ai/media/chat.html

@@ -3328,7 +3328,7 @@
     const rich = '<div class="sessrich">'
       + (files.length ? '<div class="sessfiles">' + chips + '</div>' : '')
       + '<div class="sessmeta">' + (e.model ? escFn(sessModelShort(e.model)) + ' · ' : '') + turns + ' turn' + (turns === 1 ? '' : 's') + ' ' + sessSparkSvg(e.spark) + '</div>'
-      + '<div class="sessacts"><button class="sessbtn pri" data-act="resume">Resume &#9166;</button><button class="sessbtn" data-act="done">Done</button><button class="sessbtn" data-act="rename">Rename</button><button class="sessbtn" data-act="delete">Delete</button></div>'
+      + '<div class="sessacts"><button class="sessbtn pri" data-act="resume">Resume &#9166;</button><button class="sessbtn" data-act="pin">' + (e.pinned ? 'Unpin' : 'Pin') + '</button><button class="sessbtn" data-act="done">Done</button><button class="sessbtn" data-act="rename">Rename</button><button class="sessbtn" data-act="delete">Delete</button></div>'
       + '</div>';
     return '<div class="sesscard' + st + '" data-id="' + escAttrFn(e.id || '') + '" tabindex="0" role="button" aria-label="' + escAttrFn(e.title || 'Untitled') + '">'
       + '<div class="sesstop"><span class="sessname" title="' + escAttrFn(e.title || '') + '">' + escFn(e.title || 'Untitled') + '</span>' + (e.pinned ? '<span class="sessstar" aria-label="pinned">★</span>' : '') + '</div>'

extensions/levelcode-ai/media/sessionsView.html

@@ -101,7 +101,7 @@
     const rich = '<div class="sessrich">'
       + (files.length ? '<div class="sessfiles">' + chips + '</div>' : '')
       + '<div class="sessmeta">' + (e.model ? escFn(sessModelShort(e.model)) + ' · ' : '') + turns + ' turn' + (turns === 1 ? '' : 's') + ' ' + sessSparkSvg(e.spark) + '</div>'
-      + '<div class="sessacts"><button class="sessbtn pri" data-act="resume">Resume &#9166;</button><button class="sessbtn" data-act="done">Done</button><button class="sessbtn" data-act="rename">Rename</button><button class="sessbtn" data-act="delete">Delete</button></div>'
+      + '<div class="sessacts"><button class="sessbtn pri" data-act="resume">Resume &#9166;</button><button class="sessbtn" data-act="pin">' + (e.pinned ? 'Unpin' : 'Pin') + '</button><button class="sessbtn" data-act="done">Done</button><button class="sessbtn" data-act="rename">Rename</button><button class="sessbtn" data-act="delete">Delete</button></div>'
       + '</div>';
     return '<div class="sesscard' + st + '" data-id="' + escAttrFn(e.id || '') + '" tabindex="0" role="button" aria-label="' + escAttrFn(e.title || 'Untitled') + '">'
       + '<div class="sesstop"><span class="sessname" title="' + escAttrFn(e.title || '') + '">' + escFn(e.title || 'Untitled') + '</span>' + (e.pinned ? '<span class="sessstar" aria-label="pinned">★</span>' : '') + '</div>'

extensions/levelcode-ai/package.json

@@ -441,6 +441,12 @@
           "description": "Folder to store session History in. Empty = ~/.levelcode/sessions. Each project gets its own subfolder; the files are append-only JSONL you can back up, diff, or delete by hand.",
           "scope": "machine"
         },
+        "levelcode.ai.sessions.autoArchiveDays": {
+          "type": "number",
+          "default": 30,
+          "minimum": 0,
+          "description": "Automatically archive sessions you haven't touched in this many days, to keep History focused on recent work. Archived sessions are hidden from the list but never deleted (the JSONL stays on disk), and pinned sessions are always kept. Set to 0 to turn auto-archiving off."
+        },
         "levelcode.ai.sessions.resumeBudgetPct": {
           "type": "number",
           "default": 40,

extensions/levelcode-ai/sessions.js

@@ -125,12 +125,34 @@ function createSessions(opts) {
 		return appendTo(id, events.titleEvent(String(title).trim(), iso()));
 	}
 
+	/**
+	 * Fade stale sessions out of the working set (§4.9 — "auto-archive at 30 days, keep the magic"): archive
+	 * every ACTIVE, non-pinned, non-live session whose last activity is older than `days`. Pinned means
+	 * "keep" (exempt); already archived/trashed are skipped; the live session is never touched. Append-only
+	 * (a label event each) — it NEVER deletes — and best-effort. Returns how many it archived.
+	 */
+	function autoArchiveStale(opts) {
+		const o = opts || {};
+		const days = Number.isFinite(o.days) && o.days > 0 ? o.days : 30;
+		const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : clock().getTime();
+		const cutoff = nowMs - days * 86400000;
+		const liveNow = live ? live.id : null;
+		let archived = 0;
+		for (const e of list()) {
+			if (!e || e.pinned || e.id === liveNow) { continue; }
+			if ((e.lifecycle || 'active') !== 'active') { continue; }
+			const last = Date.parse(e.updatedAt || e.createdAt || '');
+			if (Number.isFinite(last) && last < cutoff && archive(e.id)) { archived++; }
+		}
+		return archived;
+	}
+
 	/** The session index for this project (what the panel/view list). Empty (never throws) if unreadable. */
 	function list() { try { return store.loadIndex(root, slug).entries; } catch (e) { return []; } }
 
 	function liveId() { return live ? live.id : null; }
 
-	return { ensure, recordTurn, seal, resume, archive, trash, setPinned, rename, list, liveId };
+	return { ensure, recordTurn, seal, resume, archive, trash, setPinned, rename, autoArchiveStale, list, liveId };
 }
 
 module.exports = { createSessions };

extensions/levelcode-ai/test/sessions.test.js

@@ -176,4 +176,30 @@ test('MANAGER: archive / rename / trash are append-only edits that update the in
 	assert.strictEqual(m.list().find((e) => e.id === id).lifecycle, 'trashed', 'the latest label event wins');
 });
 
+test('MANAGER: autoArchiveStale fades stale, non-pinned sessions and exempts pinned + recent', () => {
+	const root = freshRoot(), slug = store.projectSlug('/aa');
+	const DAY = 86400000;
+	const T0 = Date.parse('2026-06-01T12:00:00Z');   // "now" for the sweep
+	// stamp a whole session at a chosen wall-clock time (clock injected), optionally pinned at that same time
+	const sessionAt = (ms, prompt, pin) => {
+		const mm = createSessions({ root, slug, projectPath: '/aa', now: () => new Date(ms) });
+		mm.recordTurn([{ role: 'user', content: prompt }], 'm');
+		const id = mm.liveId();
+		if (pin) { mm.setPinned(id, true); }         // pin stamped old too, so it's genuinely old AND pinned
+		mm.seal('done');
+		return id;
+	};
+	const oldId = sessionAt(T0 - 40 * DAY, 'ancient');            // 40d old, unpinned → stale
+	const recentId = sessionAt(T0 - 5 * DAY, 'recent');          // 5d old → kept
+	const pinnedOldId = sessionAt(T0 - 90 * DAY, 'kept', true);  // 90d old but pinned → exempt
+
+	const m = createSessions({ root, slug, projectPath: '/aa', now: () => new Date(T0) });
+	assert.strictEqual(m.autoArchiveStale({ days: 30, nowMs: T0 }), 1, 'only the stale, non-pinned session faded');
+	const byId = (id) => m.list().find((e) => e.id === id);
+	assert.strictEqual(byId(oldId).lifecycle, 'archived', 'the 40-day-old session auto-archived');
+	assert.strictEqual(byId(recentId).lifecycle, 'active', 'the 5-day-old session stayed');
+	assert.strictEqual(byId(pinnedOldId).lifecycle, 'active', 'a pinned session is exempt however old');
+	assert.strictEqual(m.autoArchiveStale({ days: 30, nowMs: T0 }), 0, 'idempotent — already-archived are skipped');
+});
+
 console.log('sessions: ' + n + ' tests passed');

extensions/levelcode-ai/test/sessionsUi.test.js

@@ -71,6 +71,7 @@ test('CARD (rest): two lines — title + primary-file·time; done shows NO state
 	assert.match(h, /Idempotent refunds/);
 	assert.match(h, /refund\.rb · 2h/, 'the quiet line = primary file · relative time');
 	assert.match(h, /sessstar/, 'pinned → a star');
+	assert.match(h, /data-act="pin">Unpin</, 'a pinned session offers Unpin');
 });
 
 test('CARD (state): interrupted gets the warn left-edge; a done card and an unpinned card stay bare', () => {
@@ -89,6 +90,7 @@ test('CARD (rich): the hover detail carries files, model, turns, sparkline, and
 	assert.match(h, /41 turns/);
 	assert.match(h, /<svg/, 'sparkline lives in the expand, not the resting row');
 	assert.match(h, /data-act="resume"/, 'inline actions, no … menu');
+	assert.match(h, /data-act="pin">Pin</, 'an unpinned session offers Pin');
 	assert.match(h, /class="sesschip">\+1</, '4 files → 3 chips + overflow');
 });
 
@@ -140,6 +142,14 @@ test('RESUME WIRING: the host acts on card actions and the chat replays a resume
 	assert.match(html, /function resumeTranscript/, 'via a dedicated replay (prompts + prose, tool plumbing dropped)');
 });
 
+test('HOUSEKEEPING: a Pin toggle on the card, and a 30-day auto-archive sweep on startup', () => {
+	assert.match(ext, /action === 'pin'[\s\S]{0,120}setPinned\(id, !cur\)/, 'Pin toggles the pinned flag');
+	assert.match(ext, /autoArchiveStale\(\{ days \}\)/, 'startup runs the auto-archive sweep');
+	assert.match(ext, /sessions\.autoArchiveDays/, 'gated by the setting');
+	assert.ok((pkg.contributes.configuration.properties || {})['levelcode.ai.sessions.autoArchiveDays'], 'the setting is contributed');
+	assert.ok(/data-act="pin">/.test(html) && /data-act="pin">/.test(view), 'both surfaces render the Pin action');
+});
+
 test('VIEW: the sidebar view and the modal share the EXACT same render block (no drift)', () => {
 	const grab = (s) => s.slice(s.indexOf('// [SESSIONS-PURE-START]'), s.indexOf('// [SESSIONS-PURE-END]'));
 	assert.ok(grab(view).length > 500, 'the view carries the pure block');