web/shell: fix round 1 (engine 18 patches, runtime, terminal links), re-verified; docs, README, e2e-shell

Each role's findings were fixed with tests that failed before, then attacked again by an independent
verifier. Known open findings are in the round-2 reports and are fixed in the next commit.
agent.js: the review's commit hook honours the shell's cancelled(); extension.js: agent.forDisplay.

Author: ndemianc

CLAUDE.md

@@ -110,6 +110,19 @@ the desktop app exactly as it was:
   The embedder's command API is the module's `commands` (`api.commands.executeCommand`): `create()` returns a
   disposable, so `workbench.commands` is `undefined` — a helper that used it ran inside a `try` and silently did
   nothing until a browser test asked for its effect.
+- **LevelCode Shell (`web/shell/`, `docs/WEB.md` "LevelCode Shell") is a simulated bash, not a machine.** The
+  contract is `web/shell/README.md`; where code and it disagree one is a bug. Rules: a command's output reaches a
+  terminal **only** through `src/terminal/output-filter.js`, and OSC 633 comes **only** from
+  `shell-integration.js`; a string that is not this extension's own constant (file names, command output, model
+  text, provider errors) goes through `src/sanitize.js` before it is shown or put in a note; the engine worker
+  never writes (the host validates and commits a change set, whole-or-nothing); the vendored `just-bash` is
+  patched only by `engine/vendor/just-bash/<v>/apply-patches.mjs`, anchor-checked; a change to a shared
+  `extensions/levelcode-ai` file that the desktop also runs is its own commit and leaves
+  `agentRunCommand.test.js` untouched. `web/test/e2e-shell.mjs` is the browser check; the unit gate runs with
+  `LEVELCODE_REQUIRE_XTERM=1 LEVELCODE_REQUIRE_WORKER=1` where the Code-OSS checkout is present.
+- The browser's `levelcode.*` settings are `application`-scoped except the display preferences in
+  `WORKSPACE_SETTINGS_OK` (`web/ai-extension/manifest.js`): Workspace Trust is off in a tab, so an unscoped
+  setting would be read from a folder's `.vscode/settings.json`.
 - The session store (`createSecretStorage`) belongs to every tab: no cache, one-key read-modify-write under a
   Web Lock. The refresh token is rotated on use; do not reintroduce a start-up snapshot.
 - Build: `node scripts/build-web.mjs --account <origin>` → `dist-web/`; serve with `node web/serve.mjs --dist dist-web`.

docs/WEB.md

@@ -304,10 +304,13 @@ function shellSpawnOpts(ctx, info) {
 	const folders = (vscode.workspace.workspaceFolders || []).map((f) => ({ name: f.name, root: f.uri.fsPath, uri: f.uri.toString() }));
 	return {
 		folders,
-		commit: async (changes) => {
+		// `control.cancelled()` is the shell's own word that the run was stopped while its changes were being
+		// checked: nothing is applied then (see commitShellChanges).
+		commit: async (changes, control) => {
 			const r = await commitShellChanges(changes, ctx, {
 				folders: () => workspaceFolderList(),
-				readNow: async (abs) => { try { return await host.readBytes(abs); } catch { return null; } }
+				readNow: async (abs) => { try { return await host.readBytes(abs); } catch { return null; } },
+				cancelled: () => !!(control && typeof control.cancelled === 'function' && control.cancelled())
 			});
 			return { rest: r.rest, notes: r.notes, failed: r.failed.length, refused: r.refused };
 		}

extensions/levelcode-ai/agent.js

@@ -174,13 +174,14 @@ const SHELL_API_VERSION = 1;
  * @property {WorkspaceFolderRef[]} [folders]   the workspace folders, live and in order (a shell mounts each at its root)
  * @property {Record<string,string>} [env]      extra environment
  * @property {string} [explanation]             the model's own label for the command (at most 300 characters), for a tab that mirrors it
- * @property {(changes: Change[]) => Promise<{ rest: Change[], notes: string[], failed?: number, refused?: boolean }>} [commit]
+ * @property {(changes: Change[], control?: { cancelled(): boolean }) => Promise<{ rest: Change[], notes: string[], failed?: number, refused?: boolean }>} [commit]
  *     Agent runs only. Called once, after the command has run to its END (never after Stop, a timeout or an engine
  *     limit: those apply nothing) and BEFORE 'close', with the files the command left changed. The caller validates
  *     the whole set and reviews it, or refuses it whole; it returns what the shell still has to do itself (make and
  *     remove directories), lines to append to the command's output, and how many changes it could NOT apply (the
  *     shell then does not report success). Without it the shell writes the changes straight to the workspace (the
- *     user's own terminal).
+ *     user's own terminal). `control.cancelled()` turns true when the run was stopped while the set was being
+ *     checked: the caller then applies nothing (once the first write has begun nothing interrupts it).
  *
  * @typedef {object} ChildLike  The part of a Node ChildProcess that agent.js's runCommand uses.
  * @property {number} [pid]     leave undefined: agent.js then kills with child.kill(signal)

extensions/levelcode-ai/host.js

@@ -123,7 +123,9 @@ function isProtected(rel) { return PROTECTED.some((re) => re.test(rel)); }
  *
  * @param {Change[]} changes
  * @param {{ applyEdit?: Function, applyDelete?: Function, touched?: Set<string>, editCount?: number }} ctx
- * @param {{ folders: () => Array<{name:string, root:string}>, readNow: (abs: string) => Promise<Uint8Array|null>, isDirty?: (abs: string) => boolean }} io
+ * @param {{ folders: () => Array<{name:string, root:string}>, readNow: (abs: string) => Promise<Uint8Array|null>, isDirty?: (abs: string) => boolean, cancelled?: () => boolean }} io
+ *   `cancelled` is asked between the read-only checks and once more before the first write: a Stop that arrives
+ *   while the files are being compared applies nothing. Once the first write has begun nothing interrupts it.
  * @returns {Promise<{ rest: Change[], applied: Change[], failed: Refusal[], notes: string[], refused: boolean }>}
  *   `rest` is what the SHELL itself still has to do (create and remove directories). `refused` is true when
  *   nothing was applied because the set as a whole was refused.
@@ -184,14 +186,21 @@ async function commitShellChanges(changes, ctx, io) {
 			}
 		}
 	}
+	const stopped = () => ({
+		rest: /** @type {Change[]} */ ([]), applied: /** @type {Change[]} */ ([]), failed: /** @type {Refusal[]} */ ([]), refused: true,
+		notes: ['[LevelCode Shell: stopped before any file change was applied. NONE of this command\'s file changes were applied.]'],
+	});
+	const isCancelled = () => { try { return !!(io.cancelled && io.cancelled()); } catch { return false; } };
 	// Changed on disk since the command read it (a save, another tab)? Never overwrite what someone else wrote.
 	if (!refusals.length) {
 		for (const { c } of plan) {
+			if (isCancelled()) { return stopped(); }
 			const before = c.kind === 'write' ? (c.existed ? c.before : null) : c.before;
 			const now = await io.readNow(c.path);
 			if (!same(now, before)) { refusals.push({ c, why: 'it changed while the command ran, so the command\'s result is not applied over it' }); }
 		}
 	}
+	if (isCancelled()) { return stopped(); }
 
 	if (refusals.length) {
 		/** @type {string[]} */ const notes = [];

extensions/levelcode-ai/shellCommit.js

@@ -59,6 +59,42 @@ const ids = (out) => out.failed.map((f) => f.c.path).sort();
 		assert.match(out.notes[0], /3 files changed, ready for Keep\/Undo: ~a\.txt \+new\.txt -b\.txt/);
 	});
 
+	await test('a Stop while the files are being compared applies nothing (and says so); it is asked before each check and once more before the first write', async () => {
+		const r = rig({ '/ws/a.txt': 'old', '/ws/b.txt': 'old' });
+		let calls = 0;
+		const io = Object.assign({}, r.io, { cancelled: () => { calls++; return calls > 1; } });   // true from the second question on
+		const out = await commitShellChanges([W('/ws/a.txt', 'new', 'old'), W('/ws/b.txt', 'new', 'old')], r.ctx, io);
+		assert.strictEqual(out.refused, true);
+		assert.deepStrictEqual(r.edits, []);
+		assert.deepStrictEqual(r.deletes, []);
+		assert.strictEqual(r.ctx.editCount, 0);
+		assert.deepStrictEqual(out.rest, [], 'directories are not made either');
+		assert.match(out.notes.join('\n'), /stopped before any file change was applied/);
+		assert.match(out.notes[out.notes.length - 1], /NONE of this command's file changes were applied/);
+	});
+
+	await test('a Stop that arrives after the last check but before the first write also applies nothing', async () => {
+		const r = rig({ '/ws/a.txt': 'old' });
+		let reads = 0;
+		const io = Object.assign({}, r.io, {
+			readNow: async (abs) => { reads++; return r.io.readNow(abs); },
+			cancelled: () => reads > 0,
+		});
+		const out = await commitShellChanges([W('/ws/a.txt', 'new', 'old')], r.ctx, io);
+		assert.strictEqual(out.refused, true);
+		assert.deepStrictEqual(r.edits, []);
+	});
+
+	await test('a cancelled() that throws, or an io without one, is "not cancelled"', async () => {
+		const r1 = rig({ '/ws/a.txt': 'old' });
+		const o1 = await commitShellChanges([W('/ws/a.txt', 'new', 'old')], r1.ctx, Object.assign({}, r1.io, { cancelled: () => { throw new Error('boom'); } }));
+		assert.strictEqual(o1.refused, false);
+		assert.strictEqual(r1.edits.length, 1);
+		const r2 = rig({ '/ws/a.txt': 'old' });
+		const o2 = await commitShellChanges([W('/ws/a.txt', 'new', 'old')], r2.ctx, r2.io);
+		assert.strictEqual(o2.refused, false);
+	});
+
 	await test('a deleted file is no longer verified', async () => {
 		const r = rig({ '/ws/a.txt': 'x' });
 		r.ctx.touched.add('/ws/a.txt');

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

@@ -221,6 +221,27 @@ function ctxFor(over) {
 			await p;
 		});
 
+		await test('BROWSER, the shell says the run was stopped while its changes were being checked: the commit hook applies nothing', async () => {
+			const { agent, host } = load(true);
+			const calls = registerFake(host);
+			const edits = [];
+			const enc = (s) => new TextEncoder().encode(s);
+			script = [tool('t1', 'run_command', { command: 'make-changes', explanation: 'x' }), say('Done: x')];
+			const ctx = ctxFor({ applyEdit: async (r) => { edits.push(r); return true; }, applyDelete: async () => true });
+			const p = agent.runAgent(ctx);
+			await settle(); await settle();
+			const commit = calls[0].opts.commit;
+			const out = await commit([{ kind: 'write', path: root + '/new.txt', existed: false, before: null, after: enc('hi\n') }], { cancelled: () => true });
+			assert.deepStrictEqual(edits, [], 'nothing was applied');
+			assert.strictEqual(out.refused, true);
+			assert.match(out.notes.join('\n'), /stopped before any file change was applied/);
+			const again = await commit([{ kind: 'write', path: root + '/new.txt', existed: false, before: null, after: enc('hi\n') }]);
+			assert.strictEqual(again.refused, false, 'a hook called without a control is not cancelled');
+			assert.strictEqual(edits.length, 1);
+			calls[0].child.emit('close', 0);
+			await p;
+		});
+
 		// ---- connecting: the shell extension is found lazily, once per run, and a failure is not remembered ----
 		const fakeShellApi = (over) => ({ apiVersion: 1, agent: { info: { label: 'LevelCode Shell', background: false, programs: false, network: false, commands: ['cat'] }, spawn() { return fakeChild(); } }, ...over });
 

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

@@ -60,15 +60,16 @@ export function webConfig(o = {}) {
 			// modernUI fades the top 24px of every editor into the ground (a scroll shadow that is there at scroll
 			// position zero too), which washes out line one. The editor starts below it.
 			'editor.padding.top': 24,
-			// Light or dark follows the visitor's system; the dark one is where it starts.
-			// The terminal (LevelCode Shell): a scrollback that holds a screenful of output the agent printed, no file links
-			// the workbench cannot resolve in a virtual workspace, only web links that may be followed, no toast when a
-			// command's status is not 0, and no kitty keyboard protocol (the shell does not speak it).
+			// The terminal (LevelCode Shell): a scrollback that holds a screenful of output the agent printed; the
+			// workbench's own file links off (the shell's links.js is the one path: it knows the mounts and what exists);
+			// only web links may be followed; no toast when a command's status is not 0; and no kitty keyboard
+			// protocol (the shell does not speak it).
 			'terminal.integrated.scrollback': 10000,
 			'terminal.integrated.enableFileLinks': 'off',
 			'terminal.integrated.allowedLinkSchemes': ['http', 'https', 'mailto'],
 			'terminal.integrated.showExitAlert': false,
 			'terminal.integrated.enableKittyKeyboardProtocol': false,
+			// Light or dark follows the visitor's system; the dark one is where it starts.
 			'window.autoDetectColorScheme': true,
 			'workbench.colorTheme': 'LevelCode Web Dark',
 			'workbench.preferredDarkColorTheme': 'LevelCode Web Dark',