feat(sessions): fork a session — the what-if branch

The largest designed-but-unbuilt piece of the triad. §313: "resume a copy from
any point, leaving the original intact — the what-if-I'd-told-it-to-do-X-instead
branch." Fork-from-END, as §411 settles the scoping: per-turn fork needs a
transcript picker, which is separate work.

WHICH EVENTS TRAVEL is the entire design, and the answer is not "all of them":

  user / agent / assistant   YES — this is the conversation being forked
  title                      YES, then overridden, so the fork is not a second
                             row with an identical name
  end                        NO  — that is the ORIGINAL's terminal state. Copying
                             it renders a live fork as `done` while you type
  label                      NO  — lifecycle and pinning are the original's. A
                             fork of an archived session must arrive visible, and
                             must not silently take a second pin

The copy records `forkedFrom` in its meta — §4 provenance, and what a later
branch-graph draws from. The key is written ONLY on a fork, so every existing
session file stays byte-identical and an older build reading a forked session
simply does not know it was forked rather than failing to read it.

A fork IS a resume, into a copy, so the handler calls resumeSession() on the new
id rather than duplicating the replay, the budget planning, or the honest
"resumed from a summary" note.

The sixth card button: labels now collapse below 420px (chat) / 400px (panel),
up from 360/340 — six labelled buttons need ~370px against five at ~300px, and
the row is nowrap so overshoot overflows rather than wraps. The guard added with
export already covered this; only the threshold moved.

Tests: 8 in sessions.test.js against a fixture that is sealed AND archived AND
pinned — every state a fork must not inherit. Verified non-vacuous:

  copy the end event      20/25    copy label events     20/25
  drop the (fork) suffix  21/25    drop provenance       22/25
  do not go live          23/25

All 32 suites green.

One test bug worth recording: `m.list().find(e => e.id === m.fork(id))` calls
fork() once per row against a list fetched before any fork existed. Hoisted.

Author: ndemianc

docs/levelcode-sessions-experience.md

@@ -310,7 +310,7 @@ Global rule: **nothing animates on scroll at all** — the sparkline lives in th
 
 Beyond the card and the search, the "wow" list — each grounded in the JSONL substrate so it's cheap to build:
 
-- **Fork a session** (`⇧⏎`) — resume a *copy* from any point, leaving the original intact. The "what if I'd told it to do X instead" branch. Cursor's checkpoints rewind *files*; forking rewinds the *conversation*. Both, together, is new.
+- **Fork a session** ✅ *(fork-from-end shipped)* — resume a *copy*, leaving the original intact. `sessions.fork()` seeds a new session with the original's conversation and **drops its `end` and `label` events**: a copied `end` would render a live fork as `done` while you typed into it, and a copied `label` would have a fork of an archived session born invisible in the default Active scope, or silently taking a second pin. The copy is titled `… (fork)`, records `forkedFrom` in its meta (§4 provenance, and what a later branch-graph would draw from), and becomes live — a fork *is* a resume, into a copy, so it reuses the resume path wholesale. Per-turn fork still awaits the transcript picker (§411). The "what if I'd told it to do X instead" branch. Cursor's checkpoints rewind *files*; forking rewinds the *conversation*. Both, together, is new.
 - **Files-touched search & chips** (§4.2/4.4) — find work by what it changed. The structural lead over Cursor.
 - **Activity sparkline** (§4.2) — session *shape* at a glance.
 - **The honesty layer as UI** — interrupted / reloaded / summarized states are pills and strips, not silence (§4.5, §4.7).

extensions/levelcode-ai/extension.js

@@ -936,6 +936,16 @@ async function handleSessionAction(action, id) {
 			return;
 		}
 		if (action === 'export') { await exportSession(id); return; }
+		if (action === 'fork') {
+			// A fork IS a resume, into a copy — so it reuses resumeSession wholesale rather than
+			// duplicating the transcript replay, the budget planning, or the "resumed from a summary"
+			// note. m.fork() has already made the copy live.
+			const forkId = m.fork(id);
+			if (!forkId) { vscode.window.showErrorMessage('Could not fork that session — it may have been deleted.'); return; }
+			dbg('sessions.fork', { from: id, to: forkId });
+			await resumeSession(forkId);
+			return;
+		}
 		if (action === 'restore') { m.restore(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') {

extensions/levelcode-ai/media/chat.html

@@ -1112,7 +1112,7 @@
      `title` + `aria-label` are on every button already, so nothing is lost to a pointer or a screen
      reader — only to the eye, and only when there is no room for it. */
   .sesscard { container-type: inline-size; }
-  @container (max-width: 360px) { .sesscard .sesslbl { display: none; } }
+  @container (max-width: 420px) { .sesscard .sesslbl { display: none; } }
   .sesscard .sessacts { display: none; align-items: center; gap: 6px; flex-wrap: nowrap; }
   .sesscard:hover .sesssub, .sesscard:focus-within .sesssub { display: none; }
   .sesscard:hover .sessacts, .sesscard:focus-within .sessacts { display: flex; }
@@ -3351,7 +3351,8 @@
     check: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M13.6572 3.13573C13.8583 2.9465 14.175 2.95614 14.3643 3.15722C14.5535 3.35831 14.5438 3.675 14.3428 3.86425L5.84277 11.8642C5.64597 12.0494 5.33756 12.0446 5.14648 11.8535L1.64648 8.35351C1.45121 8.15824 1.45121 7.84174 1.64648 7.64647C1.84174 7.45121 2.15825 7.45121 2.35351 7.64647L5.50976 10.8027L13.6572 3.13573Z"/></svg>',
     trash: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M10 3h3v1h-1v9l-1 1H4l-1-1V4H2V3h3V2a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1v1zM9 2H6v1h3V2zM4 13h7V4H4v9zm2-8H5v7h1V5zm1 0h1v7H7V5zm2 0h1v7H9V5z"/></svg>',
     star: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M8 1.5 L9.53 5.9 L14.18 5.99 L10.47 8.8 L11.82 13.26 L8 10.6 L4.18 13.26 L5.53 8.8 L1.82 5.99 L6.47 5.9 Z"/></svg>',
-    copy: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M4 2h7l1 1v1h1l1 1v8l-1 1H6l-1-1v-1H4l-1-1V3l1-1zm1 1v8h1V5l1-1h4V3H5zm2 3v8h6V6H7z"/></svg>'
+    copy: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M4 2h7l1 1v1h1l1 1v8l-1 1H6l-1-1v-1H4l-1-1V3l1-1zm1 1v8h1V5l1-1h4V3H5zm2 3v8h6V6H7z"/></svg>',
+    fork: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M4.5 2a2 2 0 0 0-.5 3.93v1.32c0 1.1.9 2 2 2h1.5V11a2 2 0 1 0 1 0V9.25H10c1.1 0 2-.9 2-2V5.93A2 2 0 1 0 11 5.93v1.32a1 1 0 0 1-1 1H6a1 1 0 0 1-1-1V5.93A2 2 0 0 0 4.5 2zm0 1a1 1 0 1 1 0 2 1 1 0 0 1 0-2zm7 0a1 1 0 1 1 0 2 1 1 0 0 1 0-2zM8 12a1 1 0 1 1 0 2 1 1 0 0 1 0-2z"/></svg>'
   };
   function sessActBtn(act, label, svg, cls){
     return '<button type="button" class="sessact' + (cls ? ' ' + cls : '') + '" data-act="' + act + '" title="' + label + '" aria-label="' + label + '">' + svg + '<span class="sesslbl">' + label + '</span></button>';
@@ -3377,6 +3378,7 @@
       + (e.model ? ' · ' + sessModelShort(e.model) : '') + (files.length ? ' · ' + files.join(', ') : '');
     const acts = '<span class="sessacts">'
       + sessActBtn('rename', 'Rename', SESS_IC.edit)
+      + sessActBtn('fork', 'Fork', SESS_IC.fork)
       + sessActBtn('export', 'Copy', SESS_IC.copy)
       + sessActBtn('done', 'Done', SESS_IC.check)
       + sessActBtn('delete', 'Delete', SESS_IC.trash)

extensions/levelcode-ai/media/sessionsView.html

@@ -91,7 +91,7 @@
      pane. Below the width where five labelled buttons fit, drop to icons — title + aria-label are
      already on every button, so only the eye loses anything, and only when there is no room. */
   .sesscard { container-type: inline-size; }
-  @container (max-width: 340px) { .sesscard .sesslbl { display: none; } }
+  @container (max-width: 400px) { .sesscard .sesslbl { display: none; } }
   .sesscard .sessacts { display: none; align-items: center; gap: 4px; flex-wrap: nowrap; }
   .sesscard:hover .sesssub, .sesscard:focus-within .sesssub { display: none; }
   .sesscard:hover .sessacts, .sesscard:focus-within .sessacts { display: flex; }
@@ -151,7 +151,8 @@
     check: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M13.6572 3.13573C13.8583 2.9465 14.175 2.95614 14.3643 3.15722C14.5535 3.35831 14.5438 3.675 14.3428 3.86425L5.84277 11.8642C5.64597 12.0494 5.33756 12.0446 5.14648 11.8535L1.64648 8.35351C1.45121 8.15824 1.45121 7.84174 1.64648 7.64647C1.84174 7.45121 2.15825 7.45121 2.35351 7.64647L5.50976 10.8027L13.6572 3.13573Z"/></svg>',
     trash: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M10 3h3v1h-1v9l-1 1H4l-1-1V4H2V3h3V2a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1v1zM9 2H6v1h3V2zM4 13h7V4H4v9zm2-8H5v7h1V5zm1 0h1v7H7V5zm2 0h1v7H9V5z"/></svg>',
     star: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M8 1.5 L9.53 5.9 L14.18 5.99 L10.47 8.8 L11.82 13.26 L8 10.6 L4.18 13.26 L5.53 8.8 L1.82 5.99 L6.47 5.9 Z"/></svg>',
-    copy: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M4 2h7l1 1v1h1l1 1v8l-1 1H6l-1-1v-1H4l-1-1V3l1-1zm1 1v8h1V5l1-1h4V3H5zm2 3v8h6V6H7z"/></svg>'
+    copy: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M4 2h7l1 1v1h1l1 1v8l-1 1H6l-1-1v-1H4l-1-1V3l1-1zm1 1v8h1V5l1-1h4V3H5zm2 3v8h6V6H7z"/></svg>',
+    fork: '<svg class="ci" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M4.5 2a2 2 0 0 0-.5 3.93v1.32c0 1.1.9 2 2 2h1.5V11a2 2 0 1 0 1 0V9.25H10c1.1 0 2-.9 2-2V5.93A2 2 0 1 0 11 5.93v1.32a1 1 0 0 1-1 1H6a1 1 0 0 1-1-1V5.93A2 2 0 0 0 4.5 2zm0 1a1 1 0 1 1 0 2 1 1 0 0 1 0-2zm7 0a1 1 0 1 1 0 2 1 1 0 0 1 0-2zM8 12a1 1 0 1 1 0 2 1 1 0 0 1 0-2z"/></svg>'
   };
   function sessActBtn(act, label, svg, cls){
     return '<button type="button" class="sessact' + (cls ? ' ' + cls : '') + '" data-act="' + act + '" title="' + label + '" aria-label="' + label + '">' + svg + '<span class="sesslbl">' + label + '</span></button>';
@@ -177,6 +178,7 @@
       + (e.model ? ' · ' + sessModelShort(e.model) : '') + (files.length ? ' · ' + files.join(', ') : '');
     const acts = '<span class="sessacts">'
       + sessActBtn('rename', 'Rename', SESS_IC.edit)
+      + sessActBtn('fork', 'Fork', SESS_IC.fork)
       + sessActBtn('export', 'Copy', SESS_IC.copy)
       + sessActBtn('done', 'Done', SESS_IC.check)
       + sessActBtn('delete', 'Delete', SESS_IC.trash)

extensions/levelcode-ai/sessionStore.js

@@ -74,9 +74,15 @@ function indexFile(root, slug) { return path.join(root, slug, INDEX_NAME); }
 // ── event encoding & parsing (pure) ──────────────────────────────────────────────────────────────
 
 /** The birth line — written once, so even a one-message crash leaves a listable session (design §4). */
-function metaLine(id, projectPath, createdAtIso, title) {
-	return { kind: 'meta', v: SCHEMA_V, id: String(id), project: String(projectPath == null ? '' : projectPath),
+function metaLine(id, projectPath, createdAtIso, title, forkedFrom) {
+	const m = { kind: 'meta', v: SCHEMA_V, id: String(id), project: String(projectPath == null ? '' : projectPath),
 		createdAt: String(createdAtIso), title: title == null ? null : String(title) };
+	// Provenance for a forked session, and ONLY for one — the key is absent on an ordinary session so
+	// every existing file and expectation stays byte-identical. Unknown meta keys are ignored by
+	// parseSession and deriveEntry, so this is additive in both directions: an older build reading a
+	// forked session simply does not know it was forked, rather than failing to read it.
+	if (forkedFrom != null && String(forkedFrom)) { m.forkedFrom = String(forkedFrom); }
+	return m;
 }
 
 function encodeEvent(event) { return JSON.stringify(event) + '\n'; }
@@ -151,9 +157,9 @@ function deriveEntry(meta, events) {
 // ── writing (append-only) ────────────────────────────────────────────────────────────────────────
 
 /** Create a session: its directory + the meta birth line. Idempotent-ish (a re-create just rewrites meta). */
-function createSession(root, slug, id, projectPath, createdAtIso, title) {
+function createSession(root, slug, id, projectPath, createdAtIso, title, forkedFrom) {
 	fs.mkdirSync(projectDir(root, slug), { recursive: true });
-	fs.writeFileSync(sessionFile(root, slug, id), encodeEvent(metaLine(id, projectPath, createdAtIso, title)));
+	fs.writeFileSync(sessionFile(root, slug, id), encodeEvent(metaLine(id, projectPath, createdAtIso, title, forkedFrom)));
 	return sessionFile(root, slug, id);
 }
 

extensions/levelcode-ai/sessions.js

@@ -120,6 +120,56 @@ function createSessions(opts) {
 			note: planner.describeResume(plan, turnsSummarized) };
 	}
 
+	/**
+	 * FORK a session (experience doc §6): a NEW session seeded with a copy of this one's conversation,
+	 * leaving the original completely untouched — "the what-if-I'd-told-it-to-do-X-instead branch".
+	 *
+	 * Fork-from-END, deliberately. §411 settles the scoping question: "fork-from-end first; per-turn
+	 * fork rides the transcript picker later." Forking from an arbitrary turn needs a UI for choosing
+	 * the turn, and that is a different piece of work from the copy itself.
+	 *
+	 * WHICH EVENTS TRAVEL is the whole design here, and the answer is not "all of them":
+	 *   • `user` / `agent` / `assistant`  — YES. This is the conversation; it is the thing being forked.
+	 *   • `title`                         — YES, then overridden below, so the fork is recognisable in a
+	 *                                       list where it would otherwise be a second row with the
+	 *                                       identical name.
+	 *   • `end`                           — NO. That is the original's terminal state. Copying it would
+	 *                                       make a live fork claim it had already finished, and
+	 *                                       deriveEntry would render it `done` while you typed into it.
+	 *   • `label`                         — NO. Lifecycle and pinning belong to the ORIGINAL. A fork of
+	 *                                       an archived session must arrive active, or it is born
+	 *                                       invisible in the default Active scope; a fork of a pinned
+	 *                                       one must not silently take up a second pin.
+	 *
+	 * Returns the new id, or null if the source is gone/unreadable. The caller resumes it — a fork IS a
+	 * resume, just into a copy — so nothing here duplicates the replay logic.
+	 */
+	function fork(id) {
+		let s;
+		try { s = store.readSession(store.sessionFile(root, slug, id)); }
+		catch (e) { return null; }
+
+		const src = store.deriveEntry(s.meta, s.events);
+		const newId = store.newSessionId(clock());
+		try {
+			// The meta records what it came from — provenance is the honesty guarantee everywhere else
+			// in this system (§4), and it is also what a later branch-graph would draw from.
+			store.createSession(root, slug, newId, projectPath, iso(), null, id);
+			const file = store.sessionFile(root, slug, newId);
+			for (const e of (Array.isArray(s.events) ? s.events : [])) {
+				if (!e || e.kind === 'end' || e.kind === 'label') { continue; }
+				store.appendEvent(file, e);
+			}
+			// Last, so it wins: deriveEntry takes the LATEST title event.
+			const base = src.title || 'Untitled';
+			store.appendEvent(file, events.titleEvent(/\(fork\)\s*$/.test(base) ? base : base + ' (fork)', iso()));
+			live = { id: newId, file };
+			if (state) { try { state.set('liveSessionId', newId); } catch (e2) { /* convenience */ } }
+			reindexId(newId);
+			return newId;
+		} catch (e) { return null; }
+	}
+
 	// Append-only lifecycle edits (§4.9): each writes one event, then refreshes that id's index row. All
 	// best-effort (return false rather than throw) — a History edit must never disrupt anything.
 	function appendTo(id, event) {
@@ -282,7 +332,7 @@ function createSessions(opts) {
 
 	function liveId() { return live ? live.id : null; }
 
-	return { ensure, recordTurn, seal, resume, archive, trash, restore, setPinned, rename, autoArchiveStale, digest, consolidate, transcript, refineSummary, recall, recallFacts, memoryItems, forget, recordFacts, factsList, factAction, supersedeFact, memoryPaths, list, liveId };
+	return { ensure, recordTurn, seal, resume, fork, archive, trash, restore, setPinned, rename, autoArchiveStale, digest, consolidate, transcript, refineSummary, recall, recallFacts, memoryItems, forget, recordFacts, factsList, factAction, supersedeFact, memoryPaths, list, liveId };
 }
 
 module.exports = { createSessions };

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

@@ -337,4 +337,93 @@ test('MEMORY: supersedeFact drops a stale fact from the digest but keeps it (res
 	assert.strictEqual(m.digest().facts.length, 1, 'Keep/Confirm restores it to the digest');
 });
 
+// ---- Fork (experience doc §6, "the what-if-I'd-told-it-to-do-X-instead branch") -----------------
+
+/** A sealed, archived, pinned session with two turns — every state a fork must NOT inherit. */
+function forkFixture() {
+	const root = freshRoot(), slug = 'proj';
+	const m = createSessions({ root, slug, projectPath: '/proj', memory: false });
+	m.ensure();
+	m.recordTurn(turn('add idempotency', 'refund.rb'), 'opus');
+	m.recordTurn(turn('now add retries', 'retry.rb'), 'opus');
+	const id = m.liveId();
+	m.rename(id, 'Idempotent refunds');
+	m.archive(id);
+	m.setPinned(id, true);
+	m.seal('done');
+	return { root, slug, m, id };
+}
+
+test('FORK: the copy carries the conversation and the original is left completely alone', () => {
+	const { m, id } = forkFixture();
+	const before = JSON.stringify(m.list().find((e) => e.id === id));
+
+	const forkId = m.fork(id);
+	assert.ok(forkId && forkId !== id, 'fork must produce a NEW session, not reuse the id');
+
+	const fork = m.list().find((e) => e.id === forkId);
+	assert.strictEqual(fork.turns, 2, 'the conversation did not come across');
+	assert.deepStrictEqual(fork.filesEdited, ['refund.rb', 'retry.rb'], 'the derived work came across too');
+
+	assert.strictEqual(JSON.stringify(m.list().find((e) => e.id === id)), before,
+		'forking mutated the original — the whole promise is that it does not');
+});
+
+test('FORK: state, lifecycle and pinning belong to the ORIGINAL and do not travel', () => {
+	// The event-selection rules, which are the entire design of fork(). A copied `end` would make a
+	// live fork render as `done` while you typed into it; a copied `label` would have a fork of an
+	// archived session born invisible in the default Active scope, or silently taking a second pin.
+	const { m, id } = forkFixture();
+	const forkId = m.fork(id);                       // hoisted: inside find() this runs once per row
+	const fork = m.list().find((e) => e.id === forkId);
+	assert.strictEqual(fork.state, 'active', "the original's terminal state was copied");
+	assert.strictEqual(fork.lifecycle, 'active', 'a fork of an archived session must arrive visible');
+	assert.strictEqual(fork.pinned, false, 'pinning is the original\'s, not the copy\'s');
+});
+
+test('FORK: the copy is recognisable in a list, and marked only once', () => {
+	const { m, id } = forkFixture();
+	const firstId = m.fork(id);
+	const first = m.list().find((e) => e.id === firstId);
+	assert.strictEqual(first.title, 'Idempotent refunds (fork)', 'two identical rows would be unreadable');
+
+	// Forking a fork must not stutter into "x (fork) (fork)".
+	const secondId = m.fork(first.id);
+	const second = m.list().find((e) => e.id === secondId);
+	assert.strictEqual(second.title, 'Idempotent refunds (fork)');
+});
+
+test('FORK: provenance is recorded, and only on a fork', () => {
+	const { root, slug, m, id } = forkFixture();
+	const forkId = m.fork(id);
+	const meta = (f) => store.readSession(store.sessionFile(root, slug, f)).meta;
+	assert.strictEqual(meta(forkId).forkedFrom, id, 'a fork must know where it came from (§4 provenance)');
+	assert.ok(!('forkedFrom' in meta(id)),
+		'an ordinary session gained the key — every existing file must stay byte-identical');
+});
+
+test('FORK: the copy becomes live, so the next turn appends to it and not the original', () => {
+	const { m, id } = forkFixture();
+	const forkId = m.fork(id);
+	assert.strictEqual(m.liveId(), forkId, 'a fork IS a resume, into a copy');
+
+	m.recordTurn(turn('try it differently', 'other.rb'), 'opus');
+	assert.strictEqual(m.list().find((e) => e.id === forkId).turns, 3, 'the new turn landed on the fork');
+	assert.strictEqual(m.list().find((e) => e.id === id).turns, 2, 'and NOT on the original');
+});
+
+test('FORK: a missing source fails soft, and an empty session forks without inventing turns', () => {
+	const { m } = forkFixture();
+	assert.strictEqual(m.fork('does-not-exist'), null, 'a gone session must not throw into the UI');
+	assert.strictEqual(m.fork(''), null);
+
+	const root2 = freshRoot();
+	const m2 = createSessions({ root: root2, slug: 'p', projectPath: '/p', memory: false });
+	m2.ensure();
+	const emptyId = m2.liveId();
+	const forkId = m2.fork(emptyId);
+	assert.ok(forkId, 'a session with no turns is still forkable');
+	assert.strictEqual(m2.list().find((e) => e.id === forkId).turns, 0);
+});
+
 console.log('sessions: ' + n + ' tests passed');