@elu-labs/elu 0.0.0-stage → 0.1.0

package/lib/modes.mjs

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { atomic, noSymlinks, onDisk, onDiskUp, personalDirectory, readJson, refuse, within } from './util.mjs';
+import { HOME_SECRETS } from './vendors.mjs';
+
+// Per-session permission modes. The owner picks one of MODES for a session; `locked` is
+// the profile every other run gets: read-only, no shell, no network, edits only in a
+// task worktree. Modes live in task.json and the request row, never in repository files.
+export const MODES = Object.freeze(['ask', 'auto', 'full']);
+export const PROFILES = Object.freeze(['locked', 'ask', 'auto', 'full']);
+export const PLACES = Object.freeze(['worktree', 'branch', 'here']);
+export const LABELS = Object.freeze({ locked: 'Read only', ask: 'Ask for approval', auto: 'Approve for me', full: 'Full access' });
+export const BADGES = Object.freeze({ locked: 'Read only', ask: 'Ask', auto: 'Auto', full: 'Full' });
+export const DEFAULT_MODE = 'ask';
+export const APPROVAL_WAIT_SECONDS = 1200;
+// Asks and reviews from a teammate run hardened: read-only, Claude only, no state reads.
+export const PEER_RUN_KINDS = Object.freeze(['ask', 'review']);
+export const isPeerRun = origin => PEER_RUN_KINDS.includes(origin?.kind);
+const BRANCH = /^[A-Za-z0-9._/-]{1,200}$/, BAD_BRANCH = /(^|\/)\.|\.\.|\/\/|\.lock$|^-|\/$|^\/|@\{/;
+const FOLDER_LIMIT = 8;
+
+export function checkMode(value, { allowFull = true } = {}) {
+  if (!MODES.includes(value)) refuse('Choose ask, auto, or full.');
+  if (value === 'full' && !allowFull) refuse('Schedules run with Approve for me at most.');
+  return value;
+}
+// A place is 'worktree', 'here', 'branch:<name>', or { kind, branch }. Returns { kind, branch? }.
+export function checkPlace(place, { mode } = {}) {
+  let kind, branch;
+  if (place == null) kind = 'worktree';
+  else if (typeof place === 'string') [kind, branch] = place.startsWith('branch:') ? ['branch', place.slice(7)] : [place];
+  else if (typeof place === 'object' && !Array.isArray(place)) ({ kind, branch } = place);
+  if (!PLACES.includes(kind)) refuse('Choose worktree, branch, or here.');
+  if (kind === 'here' && mode !== 'full') refuse('Here needs Full access.');
+  if (kind === 'branch') { if (typeof branch !== 'string' || !BRANCH.test(branch) || BAD_BRANCH.test(branch)) refuse('Choose a plain branch name.'); return { kind, branch }; }
+  if (branch !== undefined) refuse('Only a branch place names a branch.');
+  return { kind };
+}
+// Extra folders the lead may read this session: existing directories in the owner's home,
+// never a secret or ELU Code state folder, at most eight, each listed once.
+export function checkFolders(list, { home = os.homedir() } = {}) {
+  if (list == null) return [];
+  if (!Array.isArray(list) || list.some(item => typeof item !== 'string')) refuse('Folders must be a list of paths.');
+  const root = fs.realpathSync(home), denied = [...HOME_SECRETS.map(name => path.join(root, name)), path.resolve(personalDirectory())];
+  // The closed folders by what they are on disk, and the folders that hold one: a closed
+  // folder whose own name is a link is closed where it leads, and so is what lies above that.
+  const closed = new Set(denied.map(onDisk).filter(Boolean));
+  const holders = new Set(denied.flatMap(dir => { try { return onDiskUp(path.dirname(fs.realpathSync(dir))); } catch { return []; } }).filter(Boolean));
+  const out = [];
+  for (const item of list) {
+    if (!path.isAbsolute(item) || /[\x00-\x1f]/.test(item)) refuse('Folders must be absolute paths in your home.');
+    let real; try { if (!fs.statSync(item).isDirectory()) throw new Error('not a directory'); real = fs.realpathSync(item); } catch { refuse(`Folder not found: ${item}`); }
+    if (!within(root, real) || real === root) refuse('Folders must be inside your home, not your home itself.');
+    const here = onDiskUp(real);
+    if (denied.some(dir => within(dir, real) || within(real, dir)) || here.some(id => !id || closed.has(id)) || holders.has(here[0])) refuse('That folder holds secrets or ELU Code state.');
+    if (!out.includes(real)) out.push(real);
+  }
+  if (out.length > FOLDER_LIMIT) refuse(`Name at most ${FOLDER_LIMIT} folders.`);
+  return out;
+}
+// The named folders a turn in Ask for approval or Approve for me is denied writing to. A
+// folder may hold the workspace (the folder of all your projects holds each project and the
+// worktrees beside it) or lie inside it; such a folder is left to the workspace's own rules,
+// because in the vendors a deny wins over an allow and would refuse every edit there. So is
+// a folder that holds one the run itself writes to (keep). Compared as written and on disk.
+export function readOnlyFolders(folders, { cwd, keep = [] }) {
+  const spelled = p => { const resolved = path.resolve(p); let real = resolved; try { real = fs.realpathSync(resolved); } catch { /* Missing: as written. */ } return [...new Set([resolved, real])]; };
+  const work = spelled(cwd), kept = keep.flatMap(spelled);
+  const above = new Set([...work, ...kept].flatMap(onDiskUp).filter(Boolean)), workIds = new Set(work.map(onDisk).filter(Boolean));
+  const left = dir => spelled(dir).some(p => work.some(w => within(p, w) || within(w, p)) || kept.some(k => within(p, k)) || above.has(onDisk(p)) || onDiskUp(p).some(id => workIds.has(id)));
+  return folders.filter(dir => !left(dir));
+}
+// The lower of two profiles, so a schedule or an automatic request never exceeds its cap.
+export function capMode(mode, cap) {
+  const at = value => { const index = PROFILES.indexOf(value); if (index < 0) refuse('Choose ask, auto, or full.'); return index; };
+  return PROFILES[Math.min(at(mode), at(cap))];
+}
+const defaultFile = () => path.join(personalDirectory(), 'permissions.json');
+// The personal default for new sessions. Anything unreadable means ask.
+export function defaultMode() {
+  try { const file = defaultFile(); noSymlinks(file); if (!fs.existsSync(file)) return DEFAULT_MODE; const value = readJson(file).default; return MODES.includes(value) ? value : DEFAULT_MODE; }
+  catch { return DEFAULT_MODE; }
+}
+export function saveDefaultMode(mode) {
+  checkMode(mode); atomic(defaultFile(), { version: 1, default: mode }); return mode;
+}
+// Which profile a turn runs with, checked in order: only the owner's lead
+// gets a mode; teammate questions, reviews and read-only turns stay locked; a task without
+// permissions was saved before modes existed and stays locked.
+export function runProfile({ roleName, task, origin = null, readOnly = false }) {
+  if (roleName !== 'lead') return 'locked';
+  if (isPeerRun(origin) || readOnly) return 'locked';
+  return MODES.includes(task?.permissions) ? task.permissions : 'locked';
+}

package/lib/never-list.mjs

@@ -0,0 +1,110 @@
+// The never list in words: for the chat's Blocked line, for the instructions every model
+// gets and for what a stand-in command says when it refuses (never-shims.mjs). The rules
+// that refuse are each vendor's own, in its adapter; nothing here allows or refuses anything.
+import os from 'node:os';
+import path from 'node:path';
+import { NEVER_RULES, MERGE_RULE, SENSITIVE } from './adapters/claude.mjs';
+import { HOME_SECRETS } from './vendors.mjs';
+import { personalDirectory } from './util.mjs';
+import { approvalSummary } from './approvals.mjs';
+
+const named = rule => /^Bash\((.+):\*\)$/.exec(rule)[1];
+// The commands no mode allows, as the rules name them.
+export const NEVER_COMMANDS = Object.freeze(NEVER_RULES.map(named));
+// merge: a bot the owner lets merge pull requests; gh pr merge is then not on its list.
+export const neverCommands = ({ merge = false } = {}) => merge === true ? NEVER_COMMANDS.filter(command => command !== named(MERGE_RULE)) : [...NEVER_COMMANDS];
+// The refusal as the Blocked line and a stand-in command word it.
+export const neverSentence = command => `${command} is never allowed, in any mode`;
+// The never-list command a stand-in refused, read from what a command printed, or null. A
+// stand-in prints the sentence as a line of its own.
+export function refusedIn(output) {
+  for (const line of String(output ?? '').split('\n')) { const said = line.trim(), found = NEVER_COMMANDS.find(command => said === `${neverSentence(command)}.`); if (found) return found; }
+  return null;
+}
+// One line for the model, once a turn: the commands by name, that a longer line holding
+// one counts too, and the read-only way to list tags, which models reach for git tag to do.
+export const neverLine = options => `Never run these, alone or inside a longer command line, in any mode: ${neverCommands(options).join(', ')}. To list tags use git for-each-ref --sort=-creatordate refs/tags or git describe --tags, never git tag.`;
+
+// The commands of a shell line as a vendor's rules read it: each side of && || ; | |& & and
+// a new line, and what runs inside $( ), backticks and ( ). Quoted text is one piece.
+export function shellParts(line) {
+  const text = String(line ?? ''), out = [], stack = [{ close: null, quote: null, text: '' }];
+  const cut = () => { const frame = stack.at(-1), part = frame.text.trim(); if (part) out.push(part); frame.text = ''; };
+  for (let i = 0; i < text.length; i++) {
+    const frame = stack.at(-1), ch = text[i], two = text.slice(i, i + 2);
+    if (frame.quote === "'") { if (ch === "'") frame.quote = null; frame.text += ch; continue; }
+    if (ch === '\\') { frame.text += two; i++; continue; }
+    if (two === '$(') { stack.push({ close: ')', quote: null, text: '' }); i++; continue; }
+    if (ch === '`') { if (frame.close === '`') { cut(); stack.pop(); } else stack.push({ close: '`', quote: null, text: '' }); continue; }
+    if (frame.quote === '"') { if (ch === '"') frame.quote = null; frame.text += ch; continue; }
+    if (ch === '"' || ch === "'") { frame.quote = ch; frame.text += ch; continue; }
+    if (ch === '(') { cut(); stack.push({ close: ')', quote: null, text: '' }); continue; }
+    if (ch === ')') { cut(); if (stack.length > 1 && frame.close === ')') stack.pop(); continue; }
+    if (['&&', '||', '|&', ';;'].includes(two)) { cut(); i++; continue; }
+    // 2>&1 and &> point output somewhere; they do not end a command.
+    if (ch === '&' && (text[i - 1] === '>' || text[i + 1] === '>')) { frame.text += ch; continue; }
+    if (ch === ';' || ch === '|' || ch === '&' || ch === '\n') { cut(); continue; }
+    frame.text += ch;
+  }
+  while (stack.length) { cut(); stack.pop(); }
+  return out;
+}
+// What is dropped before a command is compared: the shell words that open a body, a leading
+// VAR=value, and the wrappers timeout, time, nice, nohup, stdbuf, command, builtin, noglob
+// and a bare xargs.
+function bare(part) {
+  let text = part.replace(/\s+/g, ' ').trim();
+  for (let was = null; was !== text;) {
+    was = text;
+    text = text.replace(/^(?:if|then|else|elif|do|while|until|!|\{)\s+/, '')
+      .replace(/^[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|[^\s"']*)\s+/, '')
+      .replace(/^(?:time|nohup|builtin|noglob)\s+/, '')
+      .replace(/^command\s+(?!-[vV]\b)/, '')
+      .replace(/^nice(?:\s+(?:-n\s*-?\d+|--adjustment=-?\d+|-\d+))?\s+/, '')
+      .replace(/^stdbuf(?:\s+-\S+)*\s+/, '')
+      .replace(/^timeout(?:\s+(?:-[sk]\s+\S+|--(?:signal|kill-after)(?:=\S+|\s+\S+)|-\S+))*\s+\S+\s+/, '')
+      .replace(/^xargs\s+(?!-)/, '');
+  }
+  return text;
+}
+// The never-list command a shell line holds, alone or as one of its parts, or null. A line
+// with a here-document is not read: its body is text, not commands, and this cannot tell
+// the two apart.
+export function neverPart(line, options) {
+  const text = String(line ?? '');
+  if (/<<[^<]/.test(text)) return null;
+  const list = neverCommands(options);
+  for (const part of shellParts(text)) { const command = bare(part), found = list.find(name => command === name || command.startsWith(`${name} `)); if (found) return found; }
+  return null;
+}
+
+const READS = ['Read', 'Grep', 'Glob'], EDITS = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];
+// The vendors whose never list is a rule or a hook on the command's text. Where stand-in
+// commands hold the list, the adapter says which command one refused (denial.never).
+const RULED = ['claude', 'grok', 'agy'];
+const within = (file, dir) => file === dir || file.startsWith(`${dir}${path.sep}`);
+const glob = name => new RegExp(`^${name.replace(/[.+^$(){}|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`);
+// Why no mode would have allowed a refused action, or null when a wider mode could.
+//   never: a never-list command; command is its name, line the whole line, alone whether
+//     the line runs nothing else. denial.never: the command a stand-in said it refused
+//   secret, own: a file that may hold secrets, or ELU Code's own, closed in every mode
+//   owner, timeout: Full access asked the owner, who said no or did not answer
+//   rule: refused in Full access by something this cannot name
+// asked: the approvals of that run, as the task keeps them.
+export function whyBlocked(denial, { mode = null, vendor = null, asked = [] } = {}) {
+  const tool = String(denial?.tool ?? ''), input = denial?.input && typeof denial.input === 'object' ? denial.input : {}, field = name => typeof input[name] === 'string' ? input[name] : '';
+  const summary = typeof denial?.summary === 'string' ? denial.summary : '';
+  const line = tool === 'Bash' ? field('command') : /^Run:? /.test(summary) ? summary.replace(/^Run:? /, '') : '';
+  if (line && RULED.includes(vendor)) { const command = neverPart(line); if (command) return { kind: 'never', command, line, alone: shellParts(line).length === 1 }; }
+  // A stand-in command refused it, wherever in the line or in a script it ran. The line is shown without the shell a vendor wraps it in.
+  if (NEVER_COMMANDS.includes(denial?.never)) { const inner = /^\S*sh -l?c (['"])(.*)\1$/s.exec(line)?.[2] ?? line; return { kind: 'never', command: denial.never, line: inner || denial.never, alone: neverPart(inner) === denial.never && shellParts(inner).length === 1 }; }
+  const file = field('file_path') || field('notebook_path') || field('path');
+  if (file && vendor === 'claude' && [...READS, ...EDITS].includes(tool)) {
+    const full = path.resolve(file);
+    if (within(full, path.resolve(personalDirectory()))) return { kind: 'own' };
+    if (READS.includes(tool) && (SENSITIVE.some(name => glob(name).test(path.basename(full))) || HOME_SECRETS.some(name => within(full, path.join(os.homedir(), name))))) return { kind: 'secret' };
+  }
+  if (mode !== 'full') return null;
+  const answer = summary || !tool ? null : asked.findLast(row => row.decision !== 'allow' && row.summary === approvalSummary(tool, input));
+  return { kind: answer ? answer.decision === 'timeout' ? 'timeout' : 'owner' : 'rule' };
+}

package/lib/never-shims.mjs

@@ -0,0 +1,311 @@
+// Stand-in commands for the never list. One small script per command word (git, gh, npm and
+// the rest) in a private folder that goes first on a session's PATH: it refuses the calls no
+// mode allows, by name, and hands every other call, arguments untouched, to the real command.
+// It reaches what a rule on the model's own command line cannot: a script the session runs,
+// sh -c, a wrapper. It is not a sandbox. A full path to the real command, a changed PATH, a
+// Git alias or another program that does the same work gets past it, and a session in Full
+// access can rewrite the folder; it is written again whenever a session starts.
+//
+// Two things are not publishing and pass: a git push whose destination is a folder on this
+// machine, and a git merge or git tag in a scratch repository under the system temporary
+// directory. A project's own tests do both.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { neverCommands, neverSentence } from './never-list.mjs';
+import { EluCodeError, quote, refuse } from './util.mjs';
+
+// The vendors whose sessions get the folder first on PATH: all of them. Where a vendor has
+// rules on the command's text as well (Claude Code, Antigravity, Grok Build), those stay;
+// the stand-ins reach what a script runs, which that text does not show.
+export const SHIM_VENDORS = Object.freeze(['codex', 'claude', 'agy', 'grok']);
+// What a stand-in exits with when it refuses.
+export const REFUSED = 126;
+// Outside the project and outside ELU Code's own state, which a session may not read: a
+// session has to be able to read and run these. Nothing in a sandboxed mode may write here.
+export function shimsBase() {
+  const data = process.env.XDG_DATA_HOME;
+  return path.join(data && path.isAbsolute(data) ? data : path.join(os.homedir(), '.local', 'share'), 'elu-code', 'never-list');
+}
+const folderOf = merge => path.join(shimsBase(), merge === true ? 'merge-allowed' : 'all');
+// The system temporary directory, links resolved: the one ELU Code itself was given, and /tmp.
+// Read when the stand-ins are written, so a session cannot name another folder by changing TMPDIR.
+export function scratchRoots() {
+  const out = [];
+  for (const dir of [os.tmpdir(), '/tmp']) { try { const real = fs.realpathSync(dir); if (real !== path.parse(real).root && !out.includes(real)) out.push(real); } catch { /* Not on this system. */ } }
+  return out;
+}
+
+const WORD = /^[a-z][a-z0-9-]*$/;
+// The never list by command word: { git: [['push'], ['tag'], ['merge']], gh: [['pr', 'merge'], ['release']], … }.
+function byWord(options) {
+  const out = {};
+  for (const command of neverCommands(options)) {
+    const [name, ...rest] = command.split(' ');
+    if (![name, ...rest].every(word => WORD.test(word)) || rest.length < 1 || rest.length > 2) throw new Error(`No stand-in can read this never-list command: ${command}`);
+    (out[name] ??= []).push(rest);
+  }
+  return out;
+}
+// What every stand-in starts with: how it refuses, and how it finds and runs the real command,
+// which is the first one on PATH outside the stand-in folders and never this file.
+const head = (shell, name, base) => `#!${shell}
+# Written by ELU Code and written again whenever a session starts. It refuses the commands no
+# mode allows and hands every other call, arguments untouched, to the real ${name}.
+set -f
+name=${name}
+base=${quote(base)}
+refuse() { printf '${neverSentence('%s')}.\\n' "$1" >&2; exit ${REFUSED}; }
+find_real() {
+  self=\${0%/*}
+  old=$IFS; IFS=:
+  for d in $PATH; do
+    IFS=$old
+    [ -n "$d" ] || d=.
+    case $d/ in "$base"/*) continue;; esac
+    [ "$d" = "$self" ] && continue
+    [ -f "$d/$name" ] && [ -x "$d/$name" ] || continue
+    [ "$d/$name" -ef "$0" ] 2>/dev/null && continue
+    real=$d/$name; return 0
+  done
+  IFS=$old
+  return 1
+}
+run() { find_real || { printf '%s: command not found\\n' "$name" >&2; exit 127; }; exec "$real" "$@"; }
+`;
+const tail = 'run "$@"\n';
+// git, read as git reads it: its own options first (these take the next word as their value),
+// then the command. Listing tags changes nothing and build scripts do it, so git tag alone and
+// git tag -l or --list pass.
+const GIT_VALUES = ['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--super-prefix', '--config-env', '--shallow-file', '--attr-source'];
+// What lets a never-list git call through when it stays on this machine. A word with no rule
+// here is refused outright.
+const GIT_LOCAL = { push: 'push_local', merge: 'scratch', tag: 'scratch' };
+// The options of git push that change nothing about where it goes. Any other option is one
+// this script cannot read, and the push is refused.
+const PUSH_FLAGS = ['all', 'branches', 'mirror', 'tags', 'follow-tags', 'no-follow-tags', 'atomic', 'no-atomic', 'dry-run', 'porcelain', 'delete', 'prune', 'no-prune', 'force', 'no-force', 'force-with-lease', 'no-force-with-lease',
+  'force-if-includes', 'no-force-if-includes', 'set-upstream', 'thin', 'no-thin', 'quiet', 'verbose', 'progress', 'no-progress', 'verify', 'no-verify', 'signed', 'no-signed', 'ipv4', 'ipv6'];
+function gitBody(paths, roots) {
+  if (paths.some(words => words.length !== 1)) throw new Error('A git entry of the never list names more than its command.');
+  const words = paths.map(([word]) => word), local = words.filter(word => GIT_LOCAL[word]), outright = words.filter(word => !GIT_LOCAL[word]);
+  const later = local.filter(word => word !== 'tag');
+  return `seen=0; sub=; more=0; first=; skip=0; nopt=0
+for a do
+  if [ $seen = 1 ]; then more=1; first=$a; break; fi
+  if [ $skip = 1 ]; then skip=0; nopt=$((nopt+1)); continue; fi
+  case $a in
+    ${GIT_VALUES.join('|')}) skip=1; nopt=$((nopt+1));;
+    -*) nopt=$((nopt+1));;
+    *) seen=1; sub=$a;;
+  esac
+done
+case $sub in
+${later.length ? `  ${later.join('|')}) ;;\n` : ''}${local.includes('tag') ? '  tag) case $more$first in 0|1-l|1--list) run "$@";; esac;;\n' : ''}${outright.length ? `  ${outright.join('|')}) refuse "$name $sub";;\n` : ''}  *) run "$@";;
+esac
+# Only a call the never list names reads on from here. Pushing to a folder on this machine and
+# working in a scratch repository under the temporary directory are not publishing, so those
+# pass. git itself is asked where the push would go and which repository the call acts on;
+# whatever it cannot say is refused.
+find_real || refuse "$name $sub"
+nl='
+'
+# The real git with this call's own options (-C, -c, --git-dir and the rest), then q1 to q5.
+gitq() {
+  qt=$#; qi=0
+  while [ $qi -lt $qt ]; do
+    qa=$1; shift; qi=$((qi+1))
+    [ $qi -gt $nopt ] || set -- "$@" "$qa"
+  done
+  "$real" "$@" \${q1:+"$q1"} \${q2:+"$q2"} \${q3:+"$q3"} \${q4:+"$q4"} \${q5:+"$q5"} </dev/null 2>/dev/null
+}
+# Whether git reads this as a place on this machine: a file URL, or a path with no host before it.
+islocal() {
+  case $1 in
+    '') return 1;;
+    file://*) return 0;;
+    *://*) return 1;;
+    *:*) case \${1%%:*} in */*) return 0;; esac; return 1;;
+  esac
+  return 0
+}
+# Whether every place git would push to for $1 (a remote, a path or a URL) is on this machine.
+dest_local() {
+  dl=$1; shift
+  [ -n "$dl" ] || return 1
+  # A remote of this repository: git gives its push URLs, with pushurl and every
+  # url.<base>.insteadOf and pushInsteadOf rule applied.
+  q1=remote q2=get-url q3=--push q4=--all q5=$dl
+  if urls=$(gitq "$@") && [ -n "$urls" ]; then
+    oldifs=$IFS; IFS=$nl
+    for u in $urls; do IFS=$oldifs; islocal "$u" || return 1; done
+    IFS=$oldifs
+    return 0
+  fi
+  # Not one. A bare name may be a remote from the user's own Git settings, so only what is
+  # written as a path or a file URL goes on, and only when nothing is set under that very name.
+  case $dl in /*|./*|../*|file://*) ;; *) return 1;; esac
+  q1=config q2=--get-all q3=remote.$dl.pushurl q4= q5=
+  gitq "$@" >/dev/null; [ $? = 1 ] || return 1
+  q3=remote.$dl.url
+  gitq "$@" >/dev/null; [ $? = 1 ] || return 1
+  # A pushInsteadOf rule that matches sends the push somewhere else.
+  q1=config q2=--get-regexp q3='^url\\..*\\.pushinsteadof$' q4= q5=
+  rules=$(gitq "$@")
+  oldifs=$IFS; IFS=$nl
+  for rule in $rules; do
+    IFS=$oldifs
+    while :; do
+      case $rule in *' '*) rule=\${rule#* };; *) break;; esac
+      case $dl in "$rule"*) return 1;; esac
+    done
+  done
+  IFS=$oldifs
+  q1=ls-remote q2=--get-url q3=$dl q4= q5=
+  u=$(gitq "$@") && islocal "$u"
+}
+# The remote a push with none named goes to, as git picks it.
+default_remote() {
+  dr=; br=
+  q1=symbolic-ref q2=-q q3=--short q4=HEAD q5=
+  br=$(gitq "$@") || br=
+  if [ -n "$br" ]; then q1=config q2=--get q3=branch.$br.pushremote q4= q5=; dr=$(gitq "$@") || dr=; fi
+  if [ -z "$dr" ]; then q1=config q2=--get q3=remote.pushdefault q4= q5=; dr=$(gitq "$@") || dr=; fi
+  if [ -z "$dr" ] && [ -n "$br" ]; then q1=config q2=--get q3=branch.$br.remote q4= q5=; dr=$(gitq "$@") || dr=; fi
+  [ -z "$dr" ] || return 0
+  # None is set for the branch: the only remote when there is one, else origin.
+  q1=remote q2= q3= q4= q5=
+  dr=$(gitq "$@") || return 1
+  case $dr in '') return 1;; *"$nl"*) dr=origin;; esac
+  return 0
+}
+push_local() {
+  pn=$((nopt+1)); pi=0; repo=; has=0; pend=0; pskip=0
+  for pa do
+    pi=$((pi+1)); [ $pi -gt $pn ] || continue
+    if [ $pskip = 1 ]; then pskip=0; continue; fi
+    if [ $pend = 0 ]; then
+      case $pa in
+        --) pend=1; continue;;
+        -o|--push-option) pskip=1; continue;;
+        -o*|--push-option=*|--force-with-lease=*|--signed=*) continue;;
+        --no-recurse-submodules|--recurse-submodules=no|--recurse-submodules=check) continue;;
+        ${PUSH_FLAGS.map(flag => `--${flag}`).join('|')}) continue;;
+        --*) return 1;;
+        -*[!fnqvud46]*) return 1;;
+        -?*) continue;;
+      esac
+    fi
+    [ $has = 1 ] || { has=1; repo=$pa; }
+  done
+  # Submodules pushed on demand go to their own remotes.
+  q1=config q2=--get q3=push.recursesubmodules q4= q5=
+  sm=$(gitq "$@") || sm=
+  case $sm in ''|no|check|false|off|0) ;; *) return 1;; esac
+  if [ -z "$sm" ]; then q1=config q2=--type=bool q3=--get q4=submodule.recurse q5=; [ "$(gitq "$@")" != true ] || return 1; fi
+  if [ $has = 0 ]; then default_remote "$@" || return 1; repo=$dr; fi
+  dest_local "$repo" "$@"
+}
+# Whether a folder lies, links resolved, inside the system temporary directory.
+intemp() {
+${roots.length ? `  it=$(cd -P -- "$1" 2>/dev/null && pwd -P) || return 1
+  case $it in ${roots.map(root => `${quote(root)}/?*`).join('|')}) return 0;; esac
+` : ''}  return 1
+}
+# Whether the repository this call acts on is a scratch one: its top level and the folder that
+# holds its history both lie inside the temporary directory. A worktree there of a repository
+# kept somewhere else is not one.
+scratch() {
+  q1=rev-parse q2=--show-toplevel q3= q4= q5=
+  top=$(gitq "$@") && [ -n "$top" ] || { q2=--absolute-git-dir; top=$(gitq "$@") && [ -n "$top" ]; } || return 1
+  q2=--path-format=absolute q3=--git-common-dir
+  common=$(gitq "$@") && [ -n "$common" ] || return 1
+  intemp "$top" && intemp "$common"
+}
+case $sub in
+${local.map(word => `  ${word}) ${GIT_LOCAL[word]} "$@" || refuse "$name ${word}";;\n`).join('')}esac
+exec "$real" "$@"
+`;
+}
+// Every other tool, read on the safe side: an option written without = may or may not take
+// the next word as its value, so both readings are tried and either one that makes a
+// never-list command refuses. skips: words the tool reads past before its command.
+const SKIPS = { gcloud: ['alpha', 'beta', 'preview'] };
+function body(name, paths) {
+  const one = paths.filter(words => words.length === 1).map(([word]) => word), two = paths.filter(words => words.length === 2);
+  const firsts = [...new Set(two.map(([word]) => word))], skips = SKIPS[name] ?? [];
+  return `looking=1; w=; prev=0
+for a do
+  case $a in
+    ${name === 'cargo' ? '+*|' : ''}-*=*) prev=0; continue;;
+    -*) prev=1; continue;;
+  esac
+${two.length ? `  if [ -n "$w" ]; then
+    case "$w $a" in ${two.map(words => `'${words.join(' ')}'`).join('|')}) refuse "$name $w $a";; esac
+    [ $prev = 1 ] || w=
+  fi
+` : ''}  if [ $looking = 1 ]; then
+    case $a in
+${skips.length ? `      ${skips.join('|')}) prev=0; continue;;\n` : ''}${one.length ? `      ${one.join('|')}) refuse "$name $a";;\n` : ''}${firsts.length ? `      ${firsts.join('|')}) w=$a;;\n` : ''}    esac
+    [ $prev = 1 ] || looking=0
+  fi
+  prev=0
+  if [ $looking = 0 ] && [ -z "$w" ]; then break; fi
+done
+${tail}`;
+}
+// The scripts, by file name. merge: a bot the owner lets merge pull requests; its gh stand-in
+// then does not refuse gh pr merge. roots: the folders that count as the temporary directory.
+export function shimScripts({ merge = false, roots = scratchRoots() } = {}) {
+  // dash starts faster than the bash that /bin/sh is on some systems; a session runs git hundreds of times.
+  const shell = fs.existsSync('/bin/dash') ? '/bin/dash' : '/bin/sh', base = shimsBase();
+  return Object.fromEntries(Object.entries(byWord({ merge })).map(([name, paths]) => [name, `${head(shell, name, base)}${name === 'git' ? gitBody(paths, roots) : body(name, paths)}`]));
+}
+// Writes the folder (0700, files 0755) and returns it. A file that already says the same is
+// left alone; anything else found there is removed, so nothing a session left in a folder
+// that is first on PATH stays for the next one.
+export function writeShims({ merge = false, roots = scratchRoots() } = {}) {
+  const base = shimsBase(), folder = folderOf(merge);
+  try {
+    fs.mkdirSync(folder, { recursive: true, mode: 0o700 });
+    for (const dir of [base, folder]) { const stat = fs.lstatSync(dir); if (!stat.isDirectory()) throw new Error(`${dir} is not a folder`); if ((stat.mode & 0o777) !== 0o700) fs.chmodSync(dir, 0o700); }
+    const scripts = shimScripts({ merge, roots });
+    for (const [name, text] of Object.entries(scripts)) {
+      const file = path.join(folder, name);
+      let same = false;
+      try { const stat = fs.lstatSync(file); same = stat.isFile() && (stat.mode & 0o777) === 0o755 && fs.readFileSync(file, 'utf8') === text; } catch { /* Written below. */ }
+      if (same) continue;
+      const draft = path.join(folder, `.${name}.${process.pid}.${crypto.randomBytes(4).toString('hex')}`);
+      fs.writeFileSync(draft, text, { mode: 0o755, flag: 'wx' }); fs.chmodSync(draft, 0o755); fs.renameSync(draft, file);
+    }
+    // A name that starts with a dot is another launch's file on its way in.
+    for (const name of fs.readdirSync(folder)) if (!Object.hasOwn(scripts, name) && !name.startsWith('.')) fs.rmSync(path.join(folder, name), { recursive: true, force: true });
+  } catch (error) {
+    if (error instanceof EluCodeError) throw error;
+    refuse(`ELU Code could not write its stand-in commands for the never list: ${error.message}`);
+  }
+  return folder;
+}
+// PATH for a session: the folder first, and no other stand-in folder after it. It returns the
+// text and changes nothing else: ELU Code's own checks never run behind the stand-ins.
+export function shimPath(current = '', { merge = false } = {}) {
+  const folder = writeShims({ merge }), base = shimsBase();
+  const rest = String(current ?? '').split(path.delimiter).filter(dir => dir && dir !== base && !dir.startsWith(`${base}${path.sep}`));
+  return [folder, ...rest].join(path.delimiter);
+}
+// Claude Code starts each command from a snapshot of the owner's shell setup. The snapshot
+// builds PATH again, which leaves the folder behind the system's own. Claude Code runs the
+// file named in CLAUDE_ENV_FILE ahead of each command, after the snapshot: this one line puts
+// the folder first again. Returns the file, beside the folder it names.
+export function shimEnvFile({ merge = false } = {}) {
+  const folder = writeShims({ merge }), file = `${folder}.path.sh`, text = `export PATH=${quote(folder)}:"$PATH"\n`;
+  try {
+    let same = false;
+    try { const stat = fs.lstatSync(file); same = stat.isFile() && fs.readFileSync(file, 'utf8') === text; } catch { /* Written below. */ }
+    if (!same) {
+      const draft = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}`;
+      fs.writeFileSync(draft, text, { mode: 0o644, flag: 'wx' }); fs.renameSync(draft, file);
+    }
+  } catch (error) { refuse(`ELU Code could not write its stand-in commands for the never list: ${error.message}`); }
+  return file;
+}

package/lib/paste.mjs

@@ -0,0 +1,56 @@
+import { StringDecoder } from 'node:string_decoder';
+
+// Bracketed paste. Asked for it, the terminal wraps pasted text in ESC[200~ … ESC[201~.
+// blessed does not know the markers: it would type the paste one key at a time, drawing the
+// screen after each one, and a newline would submit the message half way through. Here the
+// paste is taken out of the input before blessed reads keys from it and handed over whole.
+
+const START = '\x1b[200~', END = '\x1b[201~';
+const CONTROL = /[\x00-\x08\x0b-\x0c\x0e-\x1f\x7f]/g;
+
+// Where a trailing start of marker begins, or the text length when there is none. Outside a
+// paste a lone escape is the Escape key, so only two or more characters are held back.
+function partial(text, marker, least) {
+  for (let size = Math.min(marker.length - 1, text.length); size >= least; size--) if (text.endsWith(marker.slice(0, size))) return text.length - size;
+  return text.length;
+}
+
+// Pasted text as typed text: newlines of any kind, tabs, and no other control characters.
+export const pastedText = text => text.replace(/\r\n?/g, '\n').replace(CONTROL, '');
+
+// Splits a stream of input into keys for blessed and pastes for onPaste. Chunks may cut a
+// marker or a character anywhere.
+export function pasteSplitter(onKeys, onPaste) {
+  const decoder = new StringDecoder('utf8');
+  let held = '', pasting = false, pasted = '';
+  return chunk => {
+    let text = held + (typeof chunk === 'string' ? chunk : decoder.write(chunk)); held = '';
+    while (text) {
+      if (pasting) {
+        const end = text.indexOf(END);
+        if (end < 0) { const cut = partial(text, END, 1); pasted += text.slice(0, cut); held = text.slice(cut); return; }
+        pasted += text.slice(0, end); text = text.slice(end + END.length); pasting = false;
+        const value = pasted; pasted = ''; onPaste(value);
+        continue;
+      }
+      const start = text.indexOf(START);
+      if (start < 0) { const cut = partial(text, START, 2); if (cut) onKeys(text.slice(0, cut)); held = text.slice(cut); return; }
+      if (start) onKeys(text.slice(0, start));
+      text = text.slice(start + START.length); pasting = true;
+    }
+  };
+}
+
+// Turns bracketed paste on for the screen's terminal and routes each paste to onPaste, until
+// the screen is destroyed.
+export function attachPaste(screen, onPaste) {
+  const { program } = screen, input = program.input;
+  // blessed's key reader on the input, from keys.emitKeypressEvents.
+  const reader = input.listeners('data').find(fn => fn.name === 'onData');
+  if (!reader) return;
+  const split = pasteSplitter(text => reader(Buffer.from(text)), onPaste);
+  input.removeListener('data', reader); input.on('data', split);
+  program._write('\x1b[?2004h');
+  const destroy = screen.destroy.bind(screen);
+  screen.destroy = function() { program._write('\x1b[?2004l'); return destroy(); };
+}