@rho-workspace/rho 0.5.3 → 0.5.5

package/node_modules/@rho-workspace/plugin-documents/dist/index.js

@@ -499,5 +499,5 @@ export const plugin = {
                 description: 'Change a project file that is open in Rho through its shared buffer (document.read, document.edit, document.save), so a person\'s unsaved text, undo and saves stay intact.' }],
         hooks: [{ id: 'documents.unsaved-text', event: 'PreToolUse', matcher: 'Edit|Write|MultiEdit', entry: './claude-hook', timeoutSeconds: 10 }]
     },
-    components: [{ id: 'rho.editor', version: '0.2.0', owner: 'rho-plugins.documents', bindings: { document: 'document' }, ui: './ui', presentation: viewPresentation, propsSchema: { type: 'object', additionalProperties: false, properties: { title: { type: 'string', minLength: 1 } }, required: ['title'] } }]
+    components: [{ id: 'rho.editor', version: '0.2.0', owner: 'rho-plugins.documents', bindings: { document: 'document' }, ui: './ui', presentation: viewPresentation, propsSchema: { type: 'object', additionalProperties: false, properties: { title: { type: 'string', minLength: 1 }, flow: { type: 'boolean' } }, required: ['title'] } }]
 };

package/node_modules/@rho-workspace/plugin-documents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rho-workspace/plugin-documents",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "type": "module",
   "description": "Rho documents plugin",
   "license": "AGPL-3.0-only",

package/node_modules/@rho-workspace/plugin-kernel/README.md

@@ -1,6 +1,6 @@
 # Notebook
 
-`@rho-workspace/plugin-kernel` 0.5.2 keeps a live R session and a live Python
+`@rho-workspace/plugin-kernel` 0.5.4 keeps a live R session and a live Python
 session for a project, which an Agent and the person share, on this machine or on a
 server: one the person manages with serverctl, reached through it, or one reached with
 ssh.
@@ -71,6 +71,24 @@ once; Stop raises Ctrl+Break and then ends the process tree. R there cannot open
 so its answers come on a named pipe the host serves and names in `RHO_KERNEL_ANSWERS`. R and
 Python end printed lines with `\r\n` there; a cell keeps them as `\n`, as elsewhere.
 
+A session on this machine runs `Rscript` or `python3` from PATH until the project names
+another program. `kernel.run` takes `interpreter`, a program in a folder of the project
+such as the python of a virtual environment made there (`.venv/bin/python`): its folder
+must resolve inside the project, while the file may be the link a virtual environment makes
+to the Python it was made from, and it is started by that name so the environment is the
+one that runs. A path outside the project is refused (`scope`), as is one that is not a
+program (`not_found`) and one named for a session on a server. The project keeps the last
+program named for each language, so later sessions, the person's too, start with it; one
+that is gone is forgotten and the default runs. A cell naming another program than the live
+session's is refused while anyone else ran cells in that session; a session in which only
+the caller ran cells, none of them running, is stopped (recorded as stopped by that caller)
+and started again with the program named. Each session records the program it ran as it
+reported it (`sys.executable`, R's `Rscript`), relative to the project when it is in it, and
+each cell keeps the program and version that ran it, since a cell outlasts its session's
+record. The Notebook and the Overview name such a session by its environment's folder
+(`Python 3.13.5 · .venv`). Where one session ends as the next starts, at the same instant,
+the Notebook lists the end first.
+
 A session can run on a server. A place names the server, a folder there (absolute
 or `~/…`) and setup lines run in that folder before a session starts (`module load R`,
 `conda activate env`). Setup lines that make the folder (`mkdir -p`) run in the home folder
@@ -135,7 +153,9 @@ Limits (`kernelLimits`, each configurable): one session per language, at most 16
 cells waiting in each, cells of at most 64 KiB of code, the first 256 KiB of each
 cell's output (the rest is counted and the cell marked cut), at most 8 plots of at
 most 4 MiB per cell, 500 kept cells (the oldest finished ones go first, with their
-plots), 200 listed variables, 32 files named per cell (`lineageLimits`) and a 10 minute wait for a cell. A session that is not
+plots), 200 listed variables, 32 strings looked at as paths per cell (those that look like a
+file's path first, so a script's labels do not crowd out the file it writes last), 24 files
+named per cell (`lineageLimits`) and a 10 minute wait for a cell. A session that is not
 ready within 30 seconds (90 on a server) is ended. At most 16 places are named; a check
 ends after 60 seconds, a listing after 30 with at most 500 entries from 1 MiB, a signal
 after 15, and a read of serverctl's registry after 15; files larger than 64 MiB are not copied and a copy ends after 10 minutes; the
@@ -172,14 +192,55 @@ highlighting and Markdown; without them code stays plain and a server's skill sh
 written. The views add their own styles once, in the page's color and type variables, and
 use its base controls (`text-button`, `primary`, `secondary`, `inline-error`).
 
-`NotebookPage` is the Notebook as a page, `NotebookWorkSection` the newest cells for an
-overview, `useLiveValues` the sessions' values, and `askCell` and `showOnServer` bring the
-Notebook to a cell and Servers to a file. The pure `./code` entry finds the statement a
-script line belongs to (`statementAt`, `statements`, `unfinished`), writes the code that
-loads a project table or runs a script (`loadCode`, `sourceCode`), and makes Data flow's
-steps and lanes from each cell's `defined`, `used` and `files` (`lineage`, `lanes`).
-The views read at most 300 cells, show 14 lines of code and 12 of output before a click,
-keep 64 plots read, and list the 24 newest plots in Plots.
+The Notebook names, under each cell, the values it read with the cell that made the version it
+read ("Read co from R 3"), and for each value it made the later cells that read that version
+("ratio read in R 6", at most three, the rest counted); a cell named there goes to that cell and
+marks it for a moment. Variables names the cell that made each value as it is now and the cells
+that read it; on the Notebook's page these go to the cells too.
+
+Data flow draws how each result came about as a graph of values, one node per value or file: the
+files read at the top, the results at the bottom (the files written and the plots drawn, else the
+values nothing reads), the values between in rows. A node is titled with the meaning its `# means:`
+comment gives, with its name beneath; a value without one shows its name alone. Functions and
+constants are not drawn; each value names those it uses, and so does a value that changes another
+through a helper made from it (a row mask). A bar above names the results. Choosing one draws only
+what leads to it, and when every result at once would put more than six values in a row, the first
+is chosen to begin with. What leads to no result is named below the graph; choosing one draws what
+leads to it. Choosing a value shows what it comes from and what comes of it in two colors, and names
+how it was made, where, what it comes from, uses, leads to and which results it reaches; a session's
+value can be looked at, a file opened, and the cell that made a value shown in the Notebook. In a
+view of its own, or narrower than 640 px, the chosen value sits above the graph and stays in view;
+wider, it sits beside it. A narrow view titles each node in up to three lines of its meaning, a wide
+one in two. A cell that makes at least three values offers how they came about, in the same drawing.
+`ScriptFlowView` draws a script's graph for a page that follows the chosen value (`selected`,
+`onSelect`) and goes to where a value is made (`onGo`), as a script's editor does. At most 80 values
+are drawn at once, those nearest the results first, and the bar names 8 results until asked for the
+rest (`lineageViewLimits`).
+
+`NotebookPage` is the Notebook as a page, `NotebookWorkSection` the newest cells for an overview,
+`useLiveValues` the sessions' values, and `askCell` and `showOnServer` bring the Notebook to a cell
+and Servers to a file. The pure `./code` entry finds the statement a script line belongs to
+(`statementAt`, `statements`, `unfinished`), writes the code that loads a project table or runs a
+script (`loadCode`, `sourceCode`), follows each cell's `defined`, `used` and `files` to the cell
+that made each value it read (`lineage`, `cellRelations`), and makes Data flow's graph from a
+session's cells (`sessionGraph`) or a script read as text (`scriptGraph`; `scriptFlow` gives a
+script's values, files and their `# means:` comments, and `markersAbove` the comments above one
+statement), with a value's path (`graphPath`), its rows (`graphRows`), the lines behind and in front
+of it (`graphMarks`) and the value made at a line (`graphNodeAt`). In a session, a cell that makes
+its values over several statements is read statement by statement, so each value comes from what its
+own statements read, and a plot from what the statement that drew it read. A value made only from
+literals and calls that put literals together (`c()`, `paste0()`, `dict()`, not a `read.csv()` of a
+URL) is a constant. `scriptFlow` reads a script's values from its text alone, R or Python, in the
+same shape: each top-level statement makes the values it assigns outside its functions, reads the
+script's values it mentions (not what a function keeps for itself, a field after `$` or `.`, an
+argument's name, the columns in `aes()`, `vars()` or a formula, or an import) and reads or writes
+the files its strings name as the call they are given to does (`read.csv`, `write.csv`, `ggsave`,
+`to_csv`, `open(…, "w")`, or a value holding the path). A statement that changes only what the step
+before made, or makes something from nothing after a step that did, joins that step; one that makes
+and writes nothing is counted, with the values it reads, and not drawn. Nothing runs, so names built
+at run time and paths pasted from parts are not seen. A script over 512 KiB is not read and at most
+150 steps are drawn (`scriptFlowLimits`). The views read at most 300 cells, show 14 lines of code
+and 12 of output before a click, keep 64 plots read, and list the 24 newest plots in Plots.
 
 ```sh
 npm run build

package/node_modules/@rho-workspace/plugin-kernel/dist/code.d.ts

@@ -1,3 +1,5 @@
 export * from './statements.js';
 export * from './explore-code.js';
 export * from './lineage.js';
+export * from './script-flow.js';
+export * from './value-graph.js';

package/node_modules/@rho-workspace/plugin-kernel/dist/code.js

@@ -1,6 +1,9 @@
 // What the sessions know about code, for any page that hands code to them: the whole statement a
 // line belongs to, the code that loads a project table or runs a script, and how the values of a
-// session were made. Pure functions; nothing here runs code or reads the project.
+// session, or of a script read as text, were made. Pure functions; nothing here runs code or reads
+// the project.
 export * from './statements.js';
 export * from './explore-code.js';
 export * from './lineage.js';
+export * from './script-flow.js';
+export * from './value-graph.js';

package/node_modules/@rho-workspace/plugin-kernel/dist/contract.js

@@ -68,6 +68,9 @@ export const sessionSchema = obj({
     cells: { type: 'integer', minimum: 0 },
     // Where it ran (null: this machine) and the machine's own name. Sessions recorded before have neither.
     place: maybe(sessionPlaceSchema), host: maybe({ type: 'string' }),
+    // The program it ran, as the session reported it: relative to the project when it is in it
+    // (.venv/bin/python). Sessions recorded before have none.
+    program: maybe({ type: 'string' }),
 }, ['sessionId', 'language', 'state', 'version', 'pid', 'startedAt', 'startedBy', 'endedAt', 'ending', 'stop', 'problem', 'variables', 'variablesOmitted', 'variablesAt', 'cells']);
 export const outputSchema = obj({ kind: { enum: ['stdout', 'stderr', 'warning', 'error', 'plot'] }, text: { type: 'string' }, plot: { type: 'integer', minimum: 1 }, width: { type: 'integer' }, height: { type: 'integer' } }, ['kind']);
 export const cellSchema = obj({
@@ -87,6 +90,8 @@ export const cellSchema = obj({
     // the project files and folders (ending in /) its strings name, as read or written. Cells
     // recorded before have neither.
     used: { type: 'array', items: text }, files: { type: 'array', items: obj({ path: text, how: { enum: ['read', 'wrote'] } }) },
+    // The program and version that ran it. Cells recorded before have neither.
+    program: maybe({ type: 'string' }), version: maybe({ type: 'string' }),
 }, ['cellId', 'changeId', 'by', 'sessionId', 'language', 'code', 'purpose', 'queuedAt', 'startedAt', 'endedAt', 'state', 'number', 'outputs', 'bytes', 'kept', 'cut', 'interrupt', 'problem']);
 // One value of a live session as its session describes it: the kind of thing it is, short facts,
 // and one page of its rows, its elements or its parts, each part with the code that reaches it.

package/node_modules/@rho-workspace/plugin-kernel/dist/index.d.ts

@@ -27,6 +27,7 @@ export interface SessionRecord {
     cells: number;
     place?: SessionPlace | null;
     host?: string | null;
+    program?: string | null;
 }
 export interface SessionPlace {
     placeId: string;
@@ -80,6 +81,8 @@ export interface CellRecord {
         path: string;
         how: 'read' | 'wrote';
     }>;
+    program?: string | null;
+    version?: string | null;
 }
 export type InspectInput = {
     language: Language;
@@ -142,6 +145,7 @@ export declare class KernelHost {
     private loading?;
     private turn;
     private exclusive;
+    private programs;
     private placesRead?;
     private placesWriting;
     private ssh;
@@ -154,6 +158,8 @@ export declare class KernelHost {
         serverctl?: string;
         onChange?: () => void;
     });
+    private program;
+    private named;
     private transport;
     private get limits();
     private folder;
@@ -180,6 +186,7 @@ export declare class KernelHost {
         by: string;
         waitMs?: number;
         place?: string;
+        interpreter?: string;
     }): Promise<{
         cell: CellRecord;
         session: SessionRecord;

package/node_modules/@rho-workspace/plugin-kernel/dist/index.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import * as fs from 'node:fs/promises';
+import { constants as fsConstants } from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -96,6 +97,9 @@ export class KernelHost {
         this.turn = next.catch(() => { });
         return next;
     }
+    // The program each language's sessions start with when the project has named one (a path in
+    // the project, as named): the last one a cell named, until another is named.
+    programs = {};
     placesRead;
     placesWriting = Promise.resolve();
     ssh;
@@ -107,6 +111,24 @@ export class KernelHost {
         const limits = this.limits;
         this.serverctl = new Serverctl(options.serverctl ?? 'serverctl', { reuseS: 60, sessionS: limits.serverctlSessionS, readMs: limits.serverctlReadMs, skillBytes: limits.serverSkillBytes });
     }
+    // A program named for a session: one in a folder of the project, such as the python of a
+    // virtual environment made there (.venv/bin/python). Its folder must be the project's own; the
+    // file itself may be the link a virtual environment makes to the Python it was made from, and
+    // it is started by that name so the environment is the one that runs.
+    async program(named) {
+        const root = await fs.realpath(this.root), file = path.resolve(root, named);
+        const folder = await fs.realpath(path.dirname(file)).catch(() => null);
+        requireThat(folder && (folder === root || folder.startsWith(root + path.sep)), 'scope', `Name a program in a folder of this project, such as .venv/bin/python; ${named} is not.`, { interpreter: named });
+        const program = path.join(folder, path.basename(file));
+        const runs = await fs.stat(program).then(s => s.isFile(), () => false) && await fs.access(program, fsConstants.X_OK).then(() => true, () => false);
+        requireThat(runs, 'not_found', `${named} is not a program that can run here.`, { interpreter: named });
+        return program;
+    }
+    // A program in the project is named relative to it (.venv/bin/python), so the record stays true
+    // when the project moves; any other keeps the path the session reported.
+    named(live, program) {
+        return !live.place && program.startsWith(live.root + path.sep) ? path.relative(live.root, program) : program;
+    }
     transport(place) { return place.via === 'serverctl' ? this.serverctl : this.ssh; }
     get limits() { return { ...kernelLimits, ...this.options.limits }; }
     async folder() { return stateDirectory(this.root, '.rho/plugins/kernel'); }
@@ -114,6 +136,7 @@ export class KernelHost {
     load() { return this.loading ??= this.readRecord(); }
     async readRecord() {
         const state = await readJson(path.join(await this.folder(), 'state.json'), { sessions: [], cells: [] });
+        this.programs = state.programs ?? {};
         let changed = false;
         for (const s of state.sessions)
             if (s.state !== 'ended') {
@@ -134,7 +157,7 @@ export class KernelHost {
     save() {
         clearTimeout(this.saveTimer);
         this.saveTimer = undefined;
-        this.writing = this.writing.then(async () => atomicJson(path.join(await this.folder(), 'state.json'), { sessions: this.sessions ?? [], cells: this.cells }));
+        this.writing = this.writing.then(async () => atomicJson(path.join(await this.folder(), 'state.json'), { sessions: this.sessions ?? [], cells: this.cells, programs: this.programs }));
         return this.writing;
     }
     // Output arrives in many small pieces; it is written at most twice a second.
@@ -178,7 +201,7 @@ export class KernelHost {
         }
         else {
             requireThat(input.code.trim().length > 0 && Buffer.byteLength(input.code) <= this.limits.maxCodeBytes, 'invalid', `Write code of at most ${this.limits.maxCodeBytes} bytes.`, { limit: 'maxCodeBytes' });
-            const live = await this.ensure(input.language, input.by, input.place);
+            const live = await this.ensure(input.language, input.by, input.place, input.interpreter);
             requireThat(live.queue.length < this.limits.maxQueued, 'limit', `At most ${this.limits.maxQueued} cells wait in a session. Wait for some to run or interrupt the one running.`, { limit: 'maxQueued', maximum: this.limits.maxQueued });
             // The oldest finished cells make room, with their plots.
             while (this.cells.length >= this.limits.maxCells) {
@@ -202,14 +225,24 @@ export class KernelHost {
     // The language's live session, started for this caller when there is none: where the cell
     // names, else where the project runs that language (this machine unless chosen). A cell that
     // names another place than where the live session runs is refused; its values stay there.
-    async ensure(language, by, placeId) {
+    async ensure(language, by, placeId, interpreter) {
         const running = this.live.get(language), name = language === 'r' ? 'R' : 'Python';
         const where = (live) => live.place ? `on ${live.place.label}` : 'on this machine';
+        requireThat(!interpreter || !placeId || placeId === 'local', 'invalid', 'An interpreter names a program in the project on this machine; a session on a server runs that server\'s.');
+        const named = interpreter ? await this.program(interpreter) : null;
         if (running && !running.stopping) {
             requireThat(!placeId || placeId === (running.place?.placeId ?? 'local'), 'conflict', `The ${name} session runs ${where(running)}. Run the cell there, or stop that session first; its values stay until then.`, { place: running.place?.placeId ?? 'local' });
-            return running;
+            if (!named || !running.place && running.started === named)
+                return running;
+            // A session in which only this caller ran cells, none of them now, is its own to start
+            // again with the program it names. Once anyone else ran a cell there, the values are shared
+            // and only the person stops it.
+            const own = !running.place && !running.current && !running.queue.length && this.cells.filter(c => c.sessionId === running.record.sessionId).every(c => c.by === by);
+            requireThat(own, 'conflict', `The ${name} session runs ${running.record.program ?? 'another program'}${running.current || running.queue.length ? ' and has a cell running' : ', and others ran cells in it'}. Ask the person to stop it in the Notebook, then run this cell again to start one with ${interpreter}; its values stay until then.`, { program: running.started ?? running.record.program ?? null });
+            this.stopping(this.sessions, running.record.sessionId, by);
+            await running.ended;
         }
-        requireThat(!running, 'conflict', 'The session is stopping. Run the cell again when it has ended.');
+        requireThat(!this.live.get(language), 'conflict', 'The session is stopping. Run the cell again when it has ended.');
         const chosen = placeId ?? (await this.placeState()).use[language] ?? 'local';
         const place = chosen === 'local' ? null : (await this.placeState()).places.find(p => p.placeId === chosen) ?? null;
         requireThat(chosen === 'local' || place, 'not_found', `No place is named ${chosen}. Read kernel.places for the places there are.`);
@@ -220,7 +253,15 @@ export class KernelHost {
         if (old.length > this.limits.maxEndedSessions)
             this.sessions.splice(this.sessions.indexOf(old[0]), 1);
         const windows = !place && process.platform === 'win32';
-        const program = place ? 'ssh' : language === 'r' ? this.options.rscript ?? 'Rscript' : this.options.python ?? (windows ? 'python' : 'python3');
+        // A program the cell named, else the one the project named last while it is still there.
+        requireThat(!named || !place, 'invalid', `${name} runs on ${place?.label} in this project; an interpreter names a program in the project on this machine.`);
+        const kept = !named && !place && this.programs[language] ? await this.program(this.programs[language]).catch(() => null) : null;
+        if (named)
+            this.programs[language] = path.relative(await fs.realpath(this.root), named);
+        else if (!kept && this.programs[language])
+            delete this.programs[language];
+        const selected = named ?? kept;
+        const program = place ? 'ssh' : selected ?? (language === 'r' ? this.options.rscript ?? 'Rscript' : this.options.python ?? (windows ? 'python' : 'python3'));
         const root = await fs.realpath(this.root);
         // On a server the runner is sent first on the session's own input, named by its digest, so
         // the session needs nothing installed there but R or Python.
@@ -229,7 +270,9 @@ export class KernelHost {
         const pipe = windows && language === 'r' ? await answerPipe() : null;
         const child = place ? await this.transport(place).spawn(place, sessionCommand(place, language === 'r' ? 'Rscript' : 'python3', runner, source.length), root)
             : spawn(program, [runners[language], root], { cwd: root, ...ownGroup, stdio: ['pipe', 'pipe', 'pipe', 'pipe'], env: { ...process.env, MPLBACKEND: 'Agg', PYTHONUNBUFFERED: '1', ...(pipe ? { RHO_KERNEL_ANSWERS: pipe.name } : {}) } });
-        const live = { record, child, place, remotePid: null, answers: '', early: '', order: Promise.resolve(), queue: [], current: null, stopping: false, printed: '', mark: 0, held: [], answered: 0, looking: null, lookups: Promise.resolve(), pipe: pipe?.server };
+        let settle = () => { };
+        const ended = new Promise(resolve => { settle = resolve; });
+        const live = { started: selected, root, ended, settle, record, child, place, remotePid: null, answers: '', early: '', order: Promise.resolve(), queue: [], current: null, stopping: false, printed: '', mark: 0, held: [], answered: 0, looking: null, lookups: Promise.resolve(), pipe: pipe?.server };
         this.live.set(language, live);
         record.pid = place ? null : child.pid ?? null;
         const startMs = place ? this.limits.remoteStartTimeoutMs : this.limits.startTimeoutMs;
@@ -411,6 +454,8 @@ export class KernelHost {
         cell.state = 'running';
         cell.startedAt = now();
         live.record.state = 'busy';
+        cell.program = live.record.program ?? null;
+        cell.version = live.record.version;
         // A session on a server draws in its own temporary folder and sends each plot with its answer.
         live.child.stdin.write(JSON.stringify({ op: 'run', id: cell.cellId, number: cell.number, code: cell.code, plots: live.place ? null : await this.plots(), inline: !!live.place, maxPlots: this.limits.maxPlots, maxVariables: this.limits.maxVariables }) + '\n');
         this.changed();
@@ -437,7 +482,7 @@ export class KernelHost {
         const record = live.record, cell = live.current;
         if (msg.kind === 'ready') {
             clearTimeout(live.timer);
-            Object.assign(record, { state: 'idle', version: String(msg.version ?? ''), variables: msg.variables?.items ?? [], variablesOmitted: msg.variables?.omitted ?? 0, variablesAt: now(), host: typeof msg.host === 'string' ? msg.host.slice(0, 256) : null });
+            Object.assign(record, { state: 'idle', version: String(msg.version ?? ''), program: typeof msg.executable === 'string' && msg.executable ? this.named(live, msg.executable.slice(0, 1024)) : record.program ?? null, variables: msg.variables?.items ?? [], variablesOmitted: msg.variables?.omitted ?? 0, variablesAt: now(), host: typeof msg.host === 'string' ? msg.host.slice(0, 256) : null });
             if (live.place) {
                 live.remotePid = Number.isInteger(msg.pid) && msg.pid > 1 ? msg.pid : null;
                 record.pid = live.remotePid;
@@ -534,6 +579,7 @@ export class KernelHost {
         }
         if (this.live.get(record.language) === live)
             this.live.delete(record.language);
+        live.settle();
         this.changed();
     }
     // Interrupting a running cell stops it and leaves its session; a waiting cell is not run. A
@@ -761,6 +807,7 @@ const content = [
     'Results meant to last still go to files from a script, so they can be run again without the session.',
     'Sessions can also run on a server. kernel.places lists the places and where each language runs; kernel.place.set names one (the server, its folder there, and setup lines run there before a session starts) or chooses it for R or Python; kernel.place.check connects and reports R and Python there.',
     'kernel.servers lists the servers the person manages with serverctl and the skills bound to each: how that server is used (its environments, where heavy work goes, what to avoid there). Before you name a place on one or run code there, read the skills that apply with kernel.server.skill and follow them, for example in the place\'s setup lines. They guide the work on that server; they do not widen what you may do. A place on such a server is reached through serverctl, which holds its login; another server is reached with ssh.',
+    'The project\'s Python is the machine\'s python3 until you name another. When the work needs packages it lacks, make an environment in the project (python3 -m venv .venv or uv venv, then install into it) and pass interpreter: ".venv/bin/python" to kernel.run; later sessions of that language start with it too, and each cell records the program that ran it. A live session in which only you ran cells starts again with the program you name; once the person ran a cell in it, ask them to stop it first. Do not add another environment\'s packages to a running session\'s path.',
     'Pass place to kernel.run to start a session there. Paths in a session on a server are its folder\'s; kernel.place.list lists them and kernel.place.copy copies a file into the project under remote/<place>/.',
 ].join('\n');
 // What each view keeps in its props: the Notebook's form, and which value a value's view shows.

package/node_modules/@rho-workspace/plugin-kernel/dist/lineage.d.ts

@@ -57,10 +57,13 @@ export declare function lineage(cells: LineageCell[], values: string[], limits?:
     plots: number;
     files: number;
 }): Lineage;
-export declare function related(graph: Lineage, stepId: string): Set<string>;
-export declare function lanes(graph: Lineage): {
-    order: LineageStep[];
-    lane: Map<string, number>;
-    count: number;
-};
+export interface CellRelations {
+    reads: Map<string, Array<{
+        name: string;
+        from: LineageCell | null;
+    }>>;
+    readers: Map<string, Map<string, LineageCell[]>>;
+    maker: Map<string, LineageCell>;
+}
+export declare function cellRelations(cells: LineageCell[]): CellRelations;
 export declare function cellLabel(cell: LineageCell): string;

package/node_modules/@rho-workspace/plugin-kernel/dist/lineage.js

@@ -129,48 +129,25 @@ function place(steps, links) {
         step.nodes = step.nodes.map((n, i) => ({ n, i, at: toward(n.id) })).sort((a, b) => a.at - b.at || a.i - b.i).map(x => x.n);
     return layers;
 }
-// The steps a node comes from and leads to, through the links, for showing one path at a time.
-export function related(graph, stepId) {
-    const stepOfNode = new Map(graph.steps.flatMap(s => s.nodes.map(n => [n.id, s.id])));
-    const up = new Map(), down = new Map();
-    for (const link of graph.links) {
-        const from = stepOfNode.get(link.from);
-        up.set(link.to, [...up.get(link.to) ?? [], from]);
-        down.set(from, [...down.get(from) ?? [], link.to]);
-    }
-    const reach = (start, next) => {
-        const seen = new Set([start]), queue = [start];
-        while (queue.length)
-            for (const id of next.get(queue.pop()) ?? [])
-                if (!seen.has(id)) {
-                    seen.add(id);
-                    queue.push(id);
-                }
-        return seen;
-    };
-    return new Set([...reach(stepId, up), ...reach(stepId, down)]);
-}
-// The boxes in the order their cells ran (which is also an order in which each reads only from
-// boxes above it), and a lane in the margin for each value or file something read: from the line
-// that made it down past the boxes between, to each box that read it. Lanes whose spans do not
-// overlap share a place; lane 0 is nearest the boxes.
-export function lanes(graph) {
-    const order = [...graph.steps].sort((a, b) => (a.cell?.number ?? -1) - (b.cell?.number ?? -1));
-    const index = new Map(order.map((s, i) => [s.id, i])), stepOfNode = new Map(order.flatMap(s => s.nodes.map(n => [n.id, s.id])));
-    const spans = new Map();
-    for (const link of graph.links) {
-        const from = index.get(stepOfNode.get(link.from)), to = index.get(link.to), span = spans.get(link.from);
-        spans.set(link.from, { from, to: Math.max(to, span?.to ?? to) });
-    }
-    const ends = [], lane = new Map();
-    for (const [node, span] of [...spans].sort((a, b) => a[1].from - b[1].from || a[1].to - b[1].to)) {
-        let free = ends.findIndex(end => end <= span.from);
-        if (free < 0)
-            free = ends.length;
-        ends[free] = span.to;
-        lane.set(node, free);
+export function cellRelations(cells) {
+    const reads = new Map(), readers = new Map(), maker = new Map();
+    for (const cell of finished(cells)) {
+        reads.set(cell.cellId, (cell.used ?? []).map(name => {
+            const from = maker.get(name) ?? null;
+            if (from) {
+                let by = readers.get(from.cellId);
+                if (!by)
+                    readers.set(from.cellId, by = new Map());
+                by.set(name, [...by.get(name) ?? [], cell]);
+            }
+            return { name, from };
+        }));
+        for (const name of cell.removed ?? [])
+            maker.delete(name);
+        for (const name of cell.defined ?? [])
+            maker.set(name, cell);
     }
-    return { order, lane, count: ends.length };
+    return { reads, readers, maker };
 }
 // What a cell is called where it is named: its purpose (a script's lines), else its first line.
 export function cellLabel(cell) {

package/node_modules/@rho-workspace/plugin-kernel/dist/operations.js

@@ -3,9 +3,12 @@ import { cellId, cellSchema, changeId, copySchema, inspectStates, language, obje
 // Owner business contracts. Application project/authentication fields are separate.
 export const operationContracts = {
     // place names where a session that is not live yet starts ("local" is this machine); a cell
-    // naming another place than the live session's is refused.
+    // naming another place than the live session's is refused. interpreter names the program a
+    // session on this machine starts with, in a folder of the project (.venv/bin/python); the
+    // project keeps it for the language's later sessions. A cell naming another program than the
+    // live session's is refused.
     'kernel.run': {
-        inputSchema: obj({ language, code: { type: 'string', minLength: 1, maxLength: 65536 }, purpose: { type: 'string', maxLength: 200 }, changeId, waitMs: { type: 'integer', minimum: 0, maximum: 600000 }, place: placeRef }, ['language', 'code', 'changeId']),
+        inputSchema: obj({ language, code: { type: 'string', minLength: 1, maxLength: 65536 }, purpose: { type: 'string', maxLength: 200 }, changeId, waitMs: { type: 'integer', minimum: 0, maximum: 600000 }, place: placeRef, interpreter: { type: 'string', minLength: 1, maxLength: 1024 } }, ['language', 'code', 'changeId']),
         outputSchema: obj({ cell: cellSchema, session: sessionSchema }),
         requires: [], effect: 'native',
     },

package/node_modules/@rho-workspace/plugin-kernel/dist/script-flow.d.ts

@@ -0,0 +1,39 @@
+import type { Language } from './explore-code.js';
+import type { Lineage, LineageCell, LineageStep } from './lineage.js';
+export interface ScriptStep extends LineageStep {
+    cell: LineageCell;
+    from: number;
+    to: number;
+    changed: string[];
+    functions: string[];
+}
+export interface ScriptFlow extends Lineage {
+    steps: ScriptStep[];
+    quiet: number;
+    cut: number;
+    quietReads: Array<{
+        from: number;
+        to: number;
+        used: string[];
+        means?: string;
+    }>;
+    means: Map<string, string>;
+    outside: Array<{
+        name: string;
+        to: string;
+    }>;
+    tooLong: boolean;
+}
+export declare const scriptFlowLimits: {
+    bytes: number;
+    steps: number;
+};
+export declare function looksLikePath(s: string): boolean;
+export declare function markersAbove(lines: string[], line: number): Array<{
+    name: string | null;
+    text: string;
+}>;
+export declare function scriptFlow(text: string, language: Language, limits?: {
+    bytes: number;
+    steps: number;
+}, outside?: string[]): ScriptFlow;