@webship.co/workspace 0.0.0-stage → 1.0.0-alpha1

package/actions/row-actions.js

@@ -0,0 +1,262 @@
+/**
+ * Commands → Buttons (rows management), and running the actions it lets someone add.
+ *
+ * Every change answers with the editor re-rendered, on the tab it came from. Each form carries the file's
+ * mtime from when it was drawn, and a write refuses with 409 when the file changed since — another tab,
+ * or a hand edit — rather than silently writing over it. An action change made from the Rows tab carries
+ * the rest of that form, so a drag not yet saved is not lost by adding, editing or deleting an action.
+ *
+ * An action is run by id only. Its steps come from the file, never from the request; the only things a
+ * request carries into a run are option values, each checked against its option and single-quoted.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { workspaceDir } = require('../workspaces');
+const { screenStartedHtml, screenSessionName } = require('../jobs');
+const { NAME_RE } = require('../validate');
+const { lingerTail } = require('../linger');
+const { hasOwnGit } = require('../git-info');
+const { startUnlessRunning, terminalLink, isDdevProject, hasComposerJson, SAFE_PATH_RE } = require('./composer');
+const { hasPackageJson } = require('./node');
+const rowLayout = require('../row-layout');
+const catalog = require('../commands');
+
+const paneOf = (form) => (['0', '1', '2'].includes(String(form.pane)) ? Number(form.pane) : 0);
+// The card someone was working in stays open when the editor comes back.
+const editor = (send, form, message, code = 200) => send(rowLayout.rowActionsEditorHtml(message, paneOf(form),
+  { openButton: String(form.open_button || '') }), code);
+const ok = (text) => `<div class="msg assistant">✅ ${text}</div>`;
+const bad = (text) => `<div class="msg error">${text}</div>`;
+
+/** Write, or answer with why not. True when it was written. */
+function write(send, form, fn) {
+  try {
+    fn();
+    return true;
+  } catch (err) {
+    if (err && err.code === 'CHANGED') {
+      editor(send, form, bad('Row actions changed since this page was loaded (another tab, or a hand edit), so nothing was saved. This is the current state.'), 409);
+    } else {
+      editor(send, form, bad(`Could not save: ${esc(String(err && err.message || err))}`), 500);
+    }
+    return false;
+  }
+}
+
+/** The layout with whatever the Rows form carried applied to it (unchanged when the request had no form). */
+function arranged(form) {
+  const layout = rowLayout.loadRowLayoutFresh();
+  return rowLayout.arrangementFromForm(layout, form);
+}
+
+// One step a line. A line `use: <command id>` runs that command of the catalog; any other line is a command line.
+const stepsFrom = (text) => String(text || '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
+  .map((l) => { const m = /^use:\s*(\S+)$/.exec(l); return m ? { use: m[1] } : l; });
+
+async function arrange_save({ form, send }) {
+  const next = rowLayout.normalizeLayout(arranged(form));
+  if (!write(send, form, () => rowLayout.saveRowLayout(next, form.mtime))) return undefined;
+  return editor(send, form, ok('Rows saved. Reload a workspace page to see them.'));
+}
+
+async function rows_op({ form, send }) {
+  const doc = arranged(form);
+  const i = Number(form.index);
+  const op = String(form.op || '');
+  if (op === 'add') {
+    if (doc.rows.length >= rowLayout.MAX_ROWS) return editor(send, form, bad(`Up to ${rowLayout.MAX_ROWS} rows.`), 400);
+    doc.rows.push([]);
+  } else if (!Number.isInteger(i) || i < 0 || i >= doc.rows.length) {
+    return editor(send, form, bad('No such row.'), 400);
+  } else if (op === 'remove') {
+    if (doc.rows.length === 1) return editor(send, form, bad('A project row keeps at least one row.'), 400);
+    const [gone] = doc.rows.splice(i, 1);
+    doc.rows[Math.max(0, i - 1)].push(...gone);
+  } else if (op === 'up' || op === 'down') {
+    const j = op === 'up' ? i - 1 : i + 1;
+    if (j < 0 || j >= doc.rows.length) return editor(send, form, bad('That row cannot move further.'), 400);
+    [doc.rows[i], doc.rows[j]] = [doc.rows[j], doc.rows[i]];
+  } else {
+    return editor(send, form, bad('Unknown row operation.'), 400);
+  }
+  if (!write(send, form, () => rowLayout.saveRowLayout(rowLayout.normalizeLayout(doc), form.mtime))) return undefined;
+  const said = { add: 'Row added', remove: 'Row removed — its buttons moved to the row above', up: 'Row moved up', down: 'Row moved down' }[op];
+  return editor(send, form, ok(`${said}. Reload a workspace page to see it.`));
+}
+
+async function custom_add({ form, send }) {
+  const doc = arranged(form);
+  const key = form.for_button === '__new__' ? 'new' : String(form.for_button || '');
+  const field = (n) => (form[`add_${n}_${key}`] === undefined ? '' : String(form[`add_${n}_${key}`]));
+  // A command picked with nothing typed is the whole action: it takes that command's label, group and node filter.
+  const typed = stepsFrom(field('steps'));
+  const use = field('use').trim();
+  const alone = use && !typed.length ? catalog.findCommand(use) : null;
+  const label = field('label').trim() || (alone ? alone.label : '');
+  const taken = new Set(doc.custom.map((c) => c.id));
+  const base = rowLayout.slug(label);
+  let id = base;
+  for (let n = 2; taken.has(id); n += 1) id = `${base}-${n}`;
+  const entry = rowLayout.cleanCustom({
+    id, label,
+    button: key === 'new' ? field('button') : key,
+    group: field('group').trim() || (alone ? alone.group : 'Custom'),
+    when: alone && (!field('when') || field('when') === 'any') ? alone.when : (field('when') || 'any'),
+    steps: use ? [...typed, { use }] : typed,
+    keepgoing: field('keepgoing') === '1',
+    confirm: field('confirm') === '1',
+    open: field('open'),
+  });
+  const why = rowLayout.customRefusal(entry) || rowLayout.useRefusal(entry);
+  if (why) return editor(send, form, bad(`Not added: ${esc(why)}.`), 400);
+  doc.custom.push(rowLayout.customToDoc(entry));
+  if (!write(send, form, () => rowLayout.saveRowLayout(rowLayout.normalizeLayout(doc), form.mtime))) return undefined;
+  return editor(send, form, ok(`Added ${esc(entry.label)} to ${esc(rowLayout.buttonLabel(entry.button))}. Reload a workspace page to see it.`));
+}
+
+async function custom_save({ form, send }) {
+  const doc = arranged(form);
+  const id = String(form.id || '');
+  const at = doc.custom.findIndex((c) => c.id === id);
+  if (at < 0) return editor(send, form, bad('No such action — it may have been deleted.'), 404);
+  const old = rowLayout.cleanCustom(doc.custom[at]);
+  const field = (n) => (form[`edit_${n}_${id}`] === undefined ? '' : String(form[`edit_${n}_${id}`]));
+  // A step whose text did not change keeps its on_error; options are kept whole (Definition edits those).
+  const steps = stepsFrom(field('steps')).map((step, i) => {
+    const was = old.steps[i];
+    const text = typeof step === 'string' ? step : `use: ${step.use}`;
+    if (!was || !was.onError || rowLayout.stepText(was) !== text) return step;
+    return typeof step === 'string' ? { command: step, on_error: was.onError } : { use: step.use, on_error: was.onError };
+  });
+  const entry = rowLayout.cleanCustom({
+    ...rowLayout.customToDoc(old),
+    command: undefined,
+    label: field('label').trim(),
+    group: field('group').trim() || 'Custom',
+    when: field('when').trim().split(/\s+/).filter(Boolean),
+    steps,
+    keepgoing: field('keepgoing') === '1',
+    confirm: field('confirm') === '1',
+    open: field('open'),
+  });
+  const why = rowLayout.customRefusal(entry) || rowLayout.useRefusal(entry);
+  if (why) return editor(send, form, bad(`Not saved: ${esc(why)}.`), 400);
+  doc.custom[at] = rowLayout.customToDoc(entry);
+  if (!write(send, form, () => rowLayout.saveRowLayout(rowLayout.normalizeLayout(doc), form.mtime))) return undefined;
+  return editor(send, form, ok(`Saved ${esc(entry.label)}. Reload a workspace page to see it.`));
+}
+
+async function custom_remove({ form, send }) {
+  const doc = arranged(form);
+  const id = String(form.id || '');
+  if (!doc.custom.some((c) => c.id === id)) return editor(send, form, bad('No such action — only actions you added can be deleted.'), 404);
+  doc.custom = doc.custom.filter((c) => c.id !== id);
+  if (!write(send, form, () => rowLayout.saveRowLayout(rowLayout.normalizeLayout(doc), form.mtime))) return undefined;
+  return editor(send, form, ok('Action deleted.'));
+}
+
+async function layout_reset({ form, send }) {
+  if (!write(send, form, () => rowLayout.resetRowLayout(form.mtime))) return undefined;
+  return editor(send, form, ok('Back to the defaults.'));
+}
+
+function reportHtml(report) {
+  return `${report.errors.map((e) => bad(esc(e))).join('')}${report.notes.length
+    ? `<div class="msg assistant">${report.errors.length ? '' : '✅ '}${report.notes.map(esc).join(' ')}</div>` : ''}`;
+}
+
+async function definition_check({ form, send }) {
+  const report = rowLayout.checkDefinition(form.definition, String(form.mode || 'replace'), rowLayout.loadRowLayoutFresh());
+  if (!report.errors.length) report.notes.unshift('It loads cleanly.');
+  return send(reportHtml(report), report.errors.length ? 400 : 200);
+}
+
+async function definition_save({ form, send }) {
+  const report = rowLayout.checkDefinition(form.definition, String(form.mode || 'replace'), rowLayout.loadRowLayoutFresh());
+  if (report.errors.length) return editor(send, { ...form, pane: '2' }, `${bad('Nothing was saved:')}${reportHtml(report)}`, 400);
+  if (!write(send, { ...form, pane: '2' }, () => rowLayout.saveRowLayout(report.next, form.mtime))) return undefined;
+  return editor(send, { ...form, pane: '2' }, ok(`Loaded. ${report.notes.map(esc).join(' ')}`));
+}
+
+/** The action and the folder it would run in, or an answer saying why not. */
+function actionTarget({ form, send, workspace }) {
+  const projectName = String(form.projectName || '');
+  if (!NAME_RE.test(projectName)) { send(bad('Invalid project name.'), 400); return { done: true }; }
+  const entry = rowLayout.loadRowLayout().custom.find((c) => c.id === String(form.id || ''));
+  if (!entry) { send(bad('No such action — it may have been deleted in Commands → Buttons.'), 404); return { done: true }; }
+  const why = rowLayout.customRefusal(entry);
+  if (why) { send(bad(`Not running ${esc(entry.label)}: ${esc(why)}.`), 400); return { done: true }; }
+  const projectDir = path.join(workspaceDir(workspace), projectName);
+  let isDir = false;
+  try { isDir = fs.statSync(projectDir).isDirectory(); } catch (_) { /* not there */ }
+  if (!isDir) { send(bad(`No folder called ${esc(projectName)} here.`), 400); return { done: true }; }
+  if (!SAFE_PATH_RE.test(projectDir)) { send(bad('Not running it: the folder path has characters a shell line cannot carry safely.'), 400); return { done: true }; }
+  const ctx = { key: workspace, isDdev: isDdevProject(projectDir), hasComposer: hasComposerJson(projectDir), hasNode: hasPackageJson(projectDir), hasGit: hasOwnGit(projectDir) };
+  if (!rowLayout.whenMatches(entry.when, ctx)) { send(bad(`${esc(entry.label)} is only for ${esc(rowLayout.describeWhen(entry.when))}.`), 400); return { done: true }; }
+  const used = rowLayout.useRefusal(entry);
+  if (used) { send(bad(`Not running ${esc(entry.label)}: ${esc(used)}.`), 400); return { done: true }; }
+  // A command a step uses keeps its own node filter: the action's filter does not widen it.
+  for (const { cmd } of rowLayout.usedCommands(entry)) {
+    if (!rowLayout.whenMatches(cmd.when, ctx)) {
+      send(bad(`${esc(entry.label)} uses ${esc(cmd.label)}, which is only for ${esc(rowLayout.describeWhen(cmd.when))}.`), 400);
+      return { done: true };
+    }
+  }
+  return { entry, projectName, projectDir };
+}
+
+async function custom_options(args) {
+  const t = actionTarget(args);
+  if (t.done) return undefined;
+  return args.send(rowLayout.actionOptionsFormHtml(t.entry, { workspace: args.workspace, project: t.projectName }));
+}
+
+async function custom_run(args) {
+  const { form, send, workspace } = args;
+  const t = actionTarget(args);
+  if (t.done) return undefined;
+  const { entry, projectName, projectDir } = t;
+  const options = rowLayout.effectiveOptions(entry);
+  if (options.length && form.submitted !== '1') {
+    return send(bad(`${esc(entry.label)} asks for ${options.length === 1 ? 'an option' : 'options'} — run it from its menu, which opens the form.`), 400);
+  }
+  const { values, error } = rowLayout.resolveOptions({ ...entry, options }, form);
+  if (error) return send(bad(`Not running ${esc(entry.label)}: ${esc(error)}.`), 400);
+  const expanded = catalog.expandSteps(entry, { workspace, project: projectName, projectDir });
+  if (expanded.error) return send(bad(`Not running ${esc(entry.label)}: ${esc(expanded.error)}.`), 400);
+
+  const verb = `custom-${entry.id}`;
+  // The last run of this action here is about to have its log truncated: write down how it ended first.
+  rowLayout.settleRun(screenSessionName(projectName, verb, workspace));
+  const started = await startUnlessRunning({ workspace, project: projectName, projectDir, verb,
+    cmdLine: `${rowLayout.actionCommandLine(expanded.entry, values)}; ${lingerTail(entry.label)}`, label: entry.label });
+  if (started.stillRunning) {
+    return send(bad(`<code>${esc(entry.label)}</code> is still running on <strong>${esc(projectName)}</strong> — ${terminalLink(started.session, 'open it')}. Left alone.`), 409);
+  }
+  if (!started.ok) return send(screenStartedHtml(started, entry.label, projectName), started.already ? 409 : 500);
+  rowLayout.recordRun({ at: new Date().toISOString(), id: entry.id, label: entry.label, workspace, project: projectName, session: started.session });
+
+  if (entry.open === 'screen') {
+    // Its terminal, at once, in the dashboard's one modal — the same terminal the SCREENS menu opens.
+    // Nothing visible lands in the page: this only fetches the terminal into the modal and shows it.
+    return send(`<div hidden hx-get="/fragments/screen-term/${encodeURIComponent(started.session)}" hx-trigger="load" hx-target="#editor-modal-body" hx-swap="innerHTML"
+      hx-on::after:request="UIkit.modal('#editor-modal').show()"></div>`);
+  }
+  return send(`<div class="msg assistant flash-now"><code>${esc(entry.label)}</code> on <strong>${esc(projectName)}</strong> — ${terminalLink(started.session, 'open the output')}</div>`);
+}
+
+module.exports = {
+  '/actions/row-arrange-save': arrange_save,
+  '/actions/row-rows': rows_op,
+  '/actions/row-custom-add': custom_add,
+  '/actions/row-custom-save': custom_save,
+  '/actions/row-custom-remove': custom_remove,
+  '/actions/row-layout-reset': layout_reset,
+  '/actions/row-definition-check': definition_check,
+  '/actions/row-definition-save': definition_save,
+  '/actions/row-custom-options': custom_options,
+  '/actions/row-custom-run': custom_run,
+};

package/actions/screens.js

@@ -0,0 +1,270 @@
+/**
+ * The screen-session actions: watch a session's log live, or stop it. The
+ * domain lives in ../screens, shared with the modal and the Screens page.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { run, startJob, stopJob, jobFragment, runningJobKey, hostRunnerUp, hostRunnerRequest } = require('../jobs');
+const { screenLogFor, screensGridHtml, screenTargetDir, defaultSessionName } = require('../screens');
+const claudeSessions = require('../claude-sessions');
+const claudeArgs = require('../claude-args');
+const { ROOT } = require('../workspaces');
+
+// A new session: named by the user, started detached in a directory the
+// server resolves from a target token (never a path from the browser), with
+// its output teed to the workspace's own log store.
+const shq = (v) => `'${String(v).replace(/'/g, `'\\''`)}'`;
+
+/** The prompt of a session, kept beside its log with this user's permissions only. */
+function writePromptFile(session, text) {
+  const dir = path.join(ROOT, '.screens', 'prompts');
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = path.join(dir, `${session}.txt`);
+  fs.writeFileSync(file, text, { mode: 0o600 });
+  return file;
+}
+
+async function screen_new({ form, send, res }) {
+  // An empty name is not a mistake: it means "call it after where it runs", which is what the form
+  // pre-fills anyway. Refusing it made the one field nobody wants to think about the one that fails.
+  const session = String(form.session || '').trim() || defaultSessionName(form.target);
+  if (!/^[a-z0-9][a-zA-Z0-9_.-]*$/.test(session) || session.length > 60) {
+    return send('<div class="msg error">A session name starts with a lowercase letter or digit and holds only letters, digits, - _ and . (60 max).</div>', 400);
+  }
+  const dir = screenTargetDir(form.target);
+  if (!dir) return send('<div class="msg error">Unknown place to run in.</div>', 400);
+  // The name says where it runs, exactly like the sessions the row's commands
+  // start: <workspace>--<project>--<name>. A target of the workspace root or a
+  // folder contributes only what it has.
+  const target = String(form.target || '');
+  const pm = target.match(/^p:([a-z0-9_-]+):(.+)$/);
+  const wm = target.match(/^ws:([a-z0-9_-]+)$/);
+  const prefix = pm ? `${pm[1]}--${pm[2]}--` : wm ? `${wm[1]}--` : '';
+  // The form pre-fills the name with where it runs, so a name that already says it is not said twice:
+  // `dev--ha1x00b1` must not become `dev--ha1x00b1--dev--ha1x00b1`.
+  const said = prefix && (`${session}--` === prefix || session.startsWith(prefix));
+  const fullSession = `${said ? '' : prefix}${session}`.toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-').replace(/-{3,}/g, '--').slice(0, 60);
+  const logDir = path.join(ROOT, '.screens');
+  try { fs.mkdirSync(logDir, { recursive: true }); } catch (_) { /* exists */ }
+  const logFile = path.join(logDir, `${fullSession}.log`);
+  const command = String(form.command || '').trim();
+  const kind = String(form.kind || (command ? 'command' : 'shell'));
+  let inner;
+  if (kind === 'claude') {
+    // Claude Code interactively, in the real PTY screen provides. The field is
+    // the prompt it opens with; a prompt template brings its own flags along,
+    // so the session runs the same command that prompt file documents
+    // (typically --permission-mode bypassPermissions).
+    // The flags are the CLI's own, read from `claude --help` (claude-args.js) rather than typed into a
+    // free-text box: every one that arrives has to be an option that help printed, and every value has
+    // to fit the shape that option documented. A value that does not is REFUSED by name — a flag that
+    // silently did nothing is worse than one that says why.
+    const { options, error } = await claudeArgs.claudeOptions();
+    if (error) {
+      return send(`<div class="msg error">The Claude Code options could not be read on this machine: ${esc(error.slice(0, 200))}</div>`, 503);
+    }
+    const { words, problems } = claudeArgs.flagsFromForm(options, form);
+    if (problems.length) {
+      return send(`<div class="msg error">${problems.map((x) => esc(x)).join('<br>')}</div>`, 400);
+    }
+    const flags = words.join(' ');
+    // Resuming an existing conversation, by id: `claude --resume <id>` from the same directory. The id
+    // is checked against the uuid shape before it reaches a shell line, and only a session that really
+    // exists for THIS directory is accepted — an id from another project would resume nothing and say
+    // so far from here.
+    // The checkbox is what turns it on; the select only says which one. Without the checkbox a select
+    // that was left on its default would resume a session nobody asked to resume.
+    const wanted = form.resume_on ? String(form.resume || '').trim() : '';
+    const resumable = wanted && claudeSessions.isSessionId(wanted)
+      && claudeSessions.sessionsFor(dir, { limit: 200 }).some((x) => x.id === wanted)
+      ? wanted : '';
+    if (wanted && !resumable) {
+      return send(`<div class="msg error">No Claude session <code>${esc(wanted.slice(0, 40))}</code> in <code>${esc(dir)}</code> to resume.</div>`, 400);
+    }
+    const resumeFlag = resumable ? `--resume ${resumable}` : '';
+    // The opening prompt is free text, so it reaches claude through a private file and `$(cat …)`, never as
+    // a double-quoted word in the line: there `$(…)` and backticks in it would be RUN by the shell.
+    const promptFile = command ? writePromptFile(fullSession, command) : '';
+    inner = (command
+      ? `exec claude ${resumeFlag} ${flags} "$(cat ${shq(promptFile)})"`
+      : `exec claude ${resumeFlag} ${flags}`).replace(/ {2,}/g, ' ').trim();
+  } else if (kind === 'shell' || !command) {
+    inner = 'exec bash -l';
+  } else {
+    // Braces group the WHOLE command before the pipe: without them only the
+    // last segment of `a; b` is logged.
+    inner = `{ ${command} ; } 2>&1 | tee -a ${JSON.stringify(logFile)}`;
+  }
+  // The session knows where it was started without being told: the workspace, the project and the folder
+  // are in its environment, so a shell, a command or the agent never has to ask which workspace this is.
+  const sq = shq;
+  const known = { WEBSHIP_WORKSPACE: pm ? pm[1] : wm ? wm[1] : '', WEBSHIP_PROJECT: pm ? pm[2] : '', WEBSHIP_WORKSPACE_DIR: dir };
+  const vars = Object.entries(known).map(([k, v]) => `${k}=${sq(v)}`).join(' ');
+  // The runner keeps a command that starts with `exec ` interactive and pipes anything else through tee,
+  // which turns claude into --print and a shell into a pipe, so the variables go INSIDE the exec.
+  inner = /^exec /.test(inner) ? `exec env ${vars} ${inner.slice(5)}` : `export ${vars}; ${inner}`;
+  // Sessions run on the machine, not in this container — so `screen -r` in the
+  // user's own terminal reaches them, and a browser an agent opens is a window
+  // on their desktop.
+  if (!(await hostRunnerUp())) return send(runnerDownHtml(), 503);
+  const answer = await hostRunnerRequest('start', { session: fullSession, dir, owner: dir, cmd: inner });
+  if (!answer) return send(runnerDownHtml(), 503);
+  if (answer.already) return send(`<div class="msg error">A session called <strong>${esc(fullSession)}</strong> is already running.</div>`, 409);
+  if (!answer.ok) return send(`<div class="msg error">Could not start it: <pre>${esc(String(answer.error || '').slice(-250))}</pre></div>`, 500);
+
+  // Started for a work item (the form's `work_key`): the plugins note the run and say so on the item
+  // if that was asked for. The dashboard itself keeps no record of what a key means.
+  const workKey = String(form.work_key || '').toUpperCase();
+  let posted = '';
+  if (/^[A-Z][A-Z0-9]+-[0-9]+$/.test(workKey)) {
+    const wm = String(form.target || '').match(/^p:([a-z0-9_-]+):(.+)$/);
+    posted = await require('../plugin-loader').pluginScreenStarted({ session: fullSession, workKey,
+      workspace: wm ? wm[1] : '', project: wm ? wm[2] : '', dir, form });
+  }
+  // A session that exists now should show up now: the badge in the topbar, the row's SCREENS menu and
+  // the screens page all listen for this, so none of them waits out its own poll to admit that the
+  // thing you just started is running.
+  try { res.setHeader('HX-Trigger', JSON.stringify({ 'screens-changed': { session: fullSession } })); } catch (_) { /* headers already sent */ }
+  return send(posted + await screensGridHtml());
+}
+
+// The rest of the screen(1) verbs the page offers, each one command:
+//   detach    screen -S <s> -X detach     — drop every other client
+//   interrupt screen -S <s> -X stuff ^C   — interrupt what runs inside
+//   wipe      screen -wipe                — forget dead sessions
+// The dashboard's container has no screen sessions of its own any more, so a
+// screen(1) verb is asked of the machine — falling back to the container only
+// for the sessions started before the move.
+async function onHostScreen(session, args) {
+  const live = await require('../screens').listScreens();
+  const row = live.find((s) => s.session === session);
+  // Stopping goes through the host runner when the runner owns the session: it started the process
+  // group and is the one that can take the whole thing down.
+  if (row && row.where === 'host' && args.includes('quit')) {
+    const answer = await hostRunnerRequest('stop', { session });
+    if (answer && answer.ok) return { ok: true, stdout: '', stderr: '' };
+  }
+  // Everything else is screen's own, and screen IN HERE can reach it: `/run/screen` is shared with
+  // this container, which is the same reason `screen -x` attaches at all.
+  //
+  // This used to refuse every verb but quit for any session marked `host` — which is every session,
+  // since that is what listScreens labels them — and answer with "run it in your terminal" instead. So
+  // the terminal window's Ctrl-C and Detach buttons did nothing but print a command to go and type,
+  // for a session this process could drive all along. Verified from the container: `screen -S <s> -X
+  // stuff` is accepted.
+  const out = await run('screen', args, process.env.HOME, { timeoutMs: 10 * 1000 });
+  if (out.ok) return out;
+  // Only when it really fails is there something for a person to do, and then the command is the one
+  // that was actually attempted rather than a reconstruction of it.
+  const verb = args.slice(3).join(' ');
+  return { ok: false,
+    stdout: out.stdout,
+    stderr: `${String(out.stderr || out.stdout || '').trim()}\nIf this keeps failing, run it in your terminal: screen -S ${session} -X ${verb}` };
+}
+
+function runnerDownHtml() {
+  return '<div class="msg error">Sessions run on your machine, not in this container, and its runner is not up. '
+    + 'Start it once with: <code>bash ~/workspace/core/workspace-app/scripts/screen-host.sh --start</code></div>';
+}
+
+// The modes a program turns on and does not always turn off again.
+//
+// A TUI asks the terminal to report the mouse (1000/1002/1003, SGR 1006/1015), to bracket pastes
+// (2004) and for its own screen (1049). screen remembers the window's state and REPLAYS it to every
+// display that attaches afterwards — so when the program dies without putting them back, the next
+// terminal to attach has mouse reporting on with nothing consuming it, and the wheel writes
+// coordinates like `<35;80;10M` into the shell instead of scrolling. It looks like a broken terminal
+// and it is a mode nobody can see.
+//
+// There is no screen command that writes to a window's terminal: `-X echo` goes to the status line,
+// and `-X stuff` goes to the program's INPUT. So the reset is what a person would type — a printf of
+// the disable sequences — which is why this asks first and says so: it types a line into the session,
+// and that is only harmless at a shell prompt.
+const MODE_RESETS = ['?1000l', '?1001l', '?1002l', '?1003l', '?1005l', '?1006l', '?1015l', '?2004l']
+  .map((m) => `\\\\033[${m}`).join('');
+
+async function screen_verb({ form, send, pathname }) {
+  const session = String(form.session || '');
+  if (pathname === '/actions/screen-wipe') {
+    await run('screen', ['-wipe'], process.env.HOME, { timeoutMs: 10 * 1000 });
+    return send(await screensGridHtml());
+  }
+  if (!/^[a-z0-9][a-zA-Z0-9_.-]*$/.test(session)) return send('<div class="msg error">Not a screen session name.</div>', 400);
+  if (pathname === '/actions/screen-reset-modes') {
+    if (form.confirm !== 'yes') return send('<div class="msg error">Resetting types a command into the session, so it asks first.</div>', 400);
+    const out = await onHostScreen(session, ['-S', session, '-X', 'stuff', `printf "${MODE_RESETS}"\n`]);
+    return send(out.ok
+      ? `<div class="msg assistant">Cleared the mouse and paste modes on <strong>${esc(session)}</strong>.
+         Every terminal attached to it, here and in a real terminal, scrolls normally again.
+         <p class="uk-text-meta">It typed <code>printf</code> at the session's prompt — if a full-screen program was running
+         rather than a shell, that line went to the program instead and nothing was reset.</p></div>`
+      : `<div class="msg error">Could not reach ${esc(session)}: ${esc(String(out.stderr || out.stdout).slice(-200))}</div>`, out.ok ? 200 : 500);
+  }
+  const args = pathname === '/actions/screen-detach'
+    ? ['-S', session, '-X', 'detach']
+    : ['-S', session, '-X', 'stuff', '\x03'];
+  const out = await onHostScreen(session, args);
+  const what = pathname === '/actions/screen-detach' ? 'Detached every other client from' : 'Sent Ctrl-C to';
+  return send(out.ok
+    ? `<div class="msg assistant">${what} <strong>${esc(session)}</strong>.</div>`
+    : `<div class="msg error">Could not reach ${esc(session)}: ${esc(String(out.stderr || out.stdout).slice(-200))}</div>`, out.ok ? 200 : 500);
+}
+
+async function screen_watch_or_stop({ form, send, pathname, res }) {
+  const session = String(form.session || '');
+  if (!/^[a-z0-9][a-zA-Z0-9_.-]*$/.test(session)) return send('<div class="msg error">Not a screen session name.</div>', 400);
+  if (pathname === '/actions/screen-stop') {
+    if (form.confirm !== 'yes') return send('<div class="msg error">Stopping requires confirmation.</div>', 400);
+    const out = await onHostScreen(session, ['-S', session, '-X', 'quit']);
+    if (!out.ok) {
+      // A dead socket has no process to quit — `screen -wipe` is what clears it.
+      await run('screen', ['-wipe'], process.env.HOME, { timeoutMs: 10 * 1000 });
+      const still = (await require('../screens').listScreens()).some((s) => s.session === session);
+      if (still) return send(`<div class="msg error">Could not stop ${esc(session)}: ${esc(String(out.stderr || out.stdout).slice(-200))}</div>`, 500);
+    }
+    // Answer with the refreshed manager so the killed row disappears at once — and say which session
+    // went, so a terminal open on it closes itself. A pane left open on a dead session is a terminal
+    // you can still type into, and nothing on the other end.
+    try { res.setHeader('HX-Trigger', JSON.stringify({ 'screen-killed': { session }, 'screens-changed': { session } })); } catch (_) { /* headers already sent */ }
+    return send(await screensGridHtml());
+  }
+  const log = screenLogFor(session);
+  if (!log) return send('<div class="msg error">No known log for this session — reattach in a terminal instead.</div>', 404);
+  const shellLine = [
+    `tail -n +1 -F ${JSON.stringify(log)} 2>/dev/null & TP=$!`,
+    `while screen -ls 2>/dev/null | grep -q "[.]${session}[[:space:]]"; do sleep 3; done`,
+    `sleep 1; kill $TP 2>/dev/null`,
+    `echo; echo "--- the session ended; full log: ${path.basename(log)} ---"`,
+  ].join('; ');
+  // Keyed, so clicking Watch twice re-shows the running tail instead of
+  // stacking another one against the same log.
+  const key = `watch:${session}`;
+  const existing = runningJobKey(key);
+  if (existing) return send(jobFragment(existing).html);
+  const id = startJob(`📺 Watch <strong>${esc(session)}</strong>`, 'bash', ['-c', shellLine], process.env.HOME,
+    { timeoutMs: 12 * 60 * 60 * 1000, inline: true, key });
+  return send(jobFragment(id).html);
+}
+
+async function job_stop({ form, send }) {
+  const id = String(form.id || '');
+  if (!/^[0-9]+-[a-z0-9]+$/.test(id)) return send('<div class="msg error">Not a job id.</div>', 400);
+  stopJob(id);
+  return send(jobFragment(id).html);
+}
+
+module.exports = {
+  '/actions/job-stop': job_stop,
+  '/actions/screen-new': screen_new,
+  '/actions/screen-detach': screen_verb,
+  '/actions/screen-reset-modes': screen_verb,
+  '/actions/screen-interrupt': screen_verb,
+  '/actions/screen-wipe': screen_verb,
+  '/actions/screen-watch': screen_watch_or_stop,
+  '/actions/screen-stop': screen_watch_or_stop,
+  onHostScreen,
+};

package/actions/testing.js

@@ -0,0 +1,121 @@
+/**
+ * Setting a project's testing environment up, running its suite, and deleting what a run left.
+ *
+ * One module per area of the dashboard, each exporting the handlers it owns keyed by the path that
+ * reaches them. server.js merges the maps and dispatches; nothing here knows about routing, and
+ * adding an action is adding an entry rather than another branch in a 1,250-line function.
+ *
+ * Every handler takes the same context: the parsed form, the response, a `send` that writes an HTML
+ * fragment, and the workspace the request named.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { humanSize, humanTime } = require('../format');
+const { ROOT, loadWorkspaces, workspaceDir } = require('../workspaces');
+const {
+  run, jobFragment, runningJobKey, startJob, ddevProjectName, listProjects,
+  startInScreen, screenStartedHtml,
+} = require('../jobs');
+const { graphStoreDir } = require('../graphs');
+const {
+  milvusProjectName, ragInstances, ragBindings, ragInstanceFor, ragWriteBinding,
+  ragCollectionName, milvusPost, ragCollections, ragInvalidate,
+} = require('../rag');
+const {
+  findTestReports, testReportFor, invalidateTestReports, testMediaHtml, testingStackOf,
+} = require('../test-reports');
+const { NAME_RE, SCRIPT_RE } = require('../validate');
+const { commandBlock } = require('../command-block');
+const { wsUrl } = require('../urls');
+const { findGraphifyScript, findRagifyScript } = require('../workspaces');
+const { DDEV_ACTIONS } = require('../ddev');
+
+  // Delete one screenshot/recording, or all of a report's.
+  //
+  // Evidence from a finished run, and the next run writes its own — so it is deletable, unlike
+  // anything else in a project. Three things keep it safe:
+  //   * no path ever comes from the request. The name is looked up in the report's OWN file list,
+  //     the same rule the viewer uses, so a crafted name resolves to nothing.
+  //   * every resolved file is realpath-checked to be inside the project directory.
+  //   * a screenshot takes its DOM dump with it: the dump is written per failed step and is
+  //     meaningless once the picture is gone.
+async function test_media_delete({ form, res, send, workspace, pathname }) {
+    const dir = workspaceDir(workspace);
+    const projectName = String(form.projectName || '');
+    const kind = String(form.kind || '') === 'videos' ? 'videos' : 'shots';
+    if (form.confirm !== 'yes') return send('<div class="msg error">Deleting requires confirmation.</div>', 400);
+    if (!NAME_RE.test(projectName) || !fs.existsSync(path.join(dir, projectName))) {
+      return send('<div class="msg error">Unknown project.</div>', 400);
+    }
+    const t = testReportFor(dir, projectName);
+    if (!t) return send('<div class="msg error">No report for this project.</div>', 404);
+
+    const listed = kind === 'videos' ? t.report.videos : t.report.shots;
+    const wanted = String(form.name || '');
+    const picked = form.all === 'yes' ? listed : listed.filter((f) => f.name === wanted);
+    if (!picked.length) return send('<div class="msg error">That file is not in the report.</div>', 404);
+
+    // A screenshot's DOM dump shares its stem.
+    const stem = (n) => n.replace(/\.(png|jpe?g|html?)$/i, '');
+    const doms = kind === 'shots'
+      ? t.report.doms.filter((d) => picked.some((f) => stem(d.name) === stem(f.name)))
+      : [];
+
+    const root = fs.realpathSync(path.join(dir, projectName));
+    let removed = 0;
+    let bytes = 0;
+    for (const f of [...picked, ...doms]) {
+      const full = path.join(dir, projectName, f.file);
+      let real;
+      try {
+        real = fs.realpathSync(full);
+        if (!real.startsWith(root + path.sep)) continue;   // outside the project: not ours to delete
+      } catch (_) { continue; }                            // already gone
+      try {
+        bytes += fs.statSync(real).size;
+        fs.unlinkSync(real);
+        removed += 1;
+      } catch (_) { /* raced with something else */ }
+    }
+    invalidateTestReports();
+    res.setHeader('HX-Trigger', 'refresh-projects');
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    return res.end(`<div class="msg assistant test-media-flash">🗑️ Deleted ${removed} file${removed === 1 ? '' : 's'} (${esc(humanSize(bytes))}).</div>`
+      + testMediaHtml(workspace, projectName, kind, 1));
+}
+
+  // Set up a project's testing environment, and run its suite. Both are the workspace command,
+  // run as a job — they take minutes (an add-on install pulls browsers; a Webship suite is
+  // hundreds of scenarios) and both must not overlap on one project: two configures race on the
+  // same scaffold, and two runs write the same report.
+async function testing_configure({ form, res, send, workspace, pathname }) {
+    const dir = workspaceDir(workspace);
+    const projectName = String(form.projectName || '');
+    const script = 'cmd-tools-testing.sh';
+    const isRun = pathname.endsWith('-run');
+    if (!fs.existsSync(path.join(dir, script))) return send('<div class="msg error">No testing script in this workspace.</div>', 400);
+    if (!NAME_RE.test(projectName) || !listProjects(dir).includes(projectName)) {
+      return send('<div class="msg error">Unknown project.</div>', 400);
+    }
+    if (isRun && testingStackOf(dir, projectName) === 'none') {
+      return send('<div class="msg error">No testing stack in this project yet — set the environment up first.</div>', 409);
+    }
+    const jobKey = `testing:${workspace}/${projectName}`;
+    if (runningJobKey(jobKey)) {
+      return send('<div class="msg error">A testing job is already running for this project.</div>', 409);
+    }
+    const args = isRun ? [script, projectName, '--run'] : [script, projectName];
+    const started = await startInScreen({ workspace, project: projectName, projectDir: dir, ownerDir: path.join(dir, projectName),
+      verb: isRun ? 'tests' : 'tests-setup', cmdLine: `bash ${JSON.stringify(script)} ${JSON.stringify(projectName)}${isRun ? ' --run' : ''}`,
+      label: isRun ? 'run the tests' : 'set up testing' });
+    return send(screenStartedHtml(started, isRun ? 'run the tests' : 'set up testing', projectName), started.ok ? 200 : (started.already ? 409 : 500));
+}
+
+module.exports = {
+  '/actions/test-media-delete': test_media_delete,
+  '/actions/testing-configure': testing_configure,
+  '/actions/testing-run': testing_configure,
+};