@elu-labs/elu 0.0.0-stage → 0.1.0

package/lib/plan.mjs

@@ -0,0 +1,238 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { atomic, dataBlock, isObject, noSymlinks, readJson, refuse } from './util.mjs';
+import { taskDir, titleFromTask, waitLock } from './state.mjs';
+
+// A session's Task: what its owner agrees to before the work starts. A request that
+// changes files, or needs planning, comes back from the model as a proposed Task: a
+// title, a description, the goal, the objectives that say when it is done, a priority and
+// a severity. The owner approves or rejects it, and ELU Code starts an editing turn only
+// for an approved Task. After approval the model splits the work into subtasks and
+// changes them as it likes; the goal and the objectives are the owner's, and change only
+// through a new proposal.
+// Tasks are kept in plan.json beside the session record, written whole under a lock of
+// their own. A turn holds the session record for its whole length and writes it back at
+// its end, so an approval kept there would be overwritten; here it never is.
+
+export const PRIORITIES = Object.freeze(['urgent', 'high', 'medium', 'low']);
+export const SEVERITIES = Object.freeze(['critical', 'high', 'medium', 'low']);
+export const TASK_LIMITS = Object.freeze({ title: 80, description: 2000, goal: 500, objective: 300, objectives: 8, subtask: 200, subtasks: 30, kept: 20 });
+const STATES = ['proposed', 'approved', 'rejected', 'done'], STEPS = ['todo', 'doing', 'done'];
+// Control characters, and the marks that reorder or hide text on a screen.
+const CONTROL = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/;
+// Where a session's Tasks are kept.
+export const planFile = (repo, id) => path.join(taskDir(repo, id), 'plan.json');
+const file = planFile;
+const stored = row => isObject(row) && typeof row.id === 'string' && typeof row.title === 'string' && STATES.includes(row.state) && Array.isArray(row.objectives) && Array.isArray(row.subtasks) && Array.isArray(row.met);
+
+// Every Task of a session, oldest first. An unreadable file reads as none, so it never
+// stops a turn; with none, the next request is planned again.
+export function sessionTasks(repo, id) {
+  try {
+    const target = file(repo, id); noSymlinks(target);
+    if (!fs.existsSync(target)) return [];
+    const value = readJson(target);
+    return Array.isArray(value?.tasks) ? value.tasks.filter(stored) : [];
+  } catch { return []; }
+}
+// The Task a session shows: its newest one.
+export const currentTask = (repo, id) => sessionTasks(repo, id).at(-1) ?? null;
+// The Task whose work is going on: the newest approved one.
+export const openTask = rows => rows.findLast(row => row.state === 'approved') ?? null;
+// The Task that waits for the owner: only ever the newest.
+export const waitingTask = rows => rows.at(-1)?.state === 'proposed' ? rows.at(-1) : null;
+function change(repo, id, edit) {
+  const release = waitLock(repo, `plan-${id}`, 200);
+  try { const rows = sessionTasks(repo, id), result = edit(rows); atomic(file(repo, id), { version: 1, tasks: rows.slice(-TASK_LIMITS.kept) }); return result; }
+  finally { release(); }
+}
+
+// A Task is the model's text, so it is checked like any other: plain text of a stated
+// length, a priority and a severity from the lists. Markup is shown as typed, never run.
+function words(value, max, label, { lines = false } = {}) {
+  if (typeof value !== 'string') refuse(`The Task needs ${label}.`);
+  const text = lines ? value.replace(/\r\n?/g, '\n').replace(/\t/g, ' ').split('\n').map(row => row.trimEnd()).join('\n').replace(/\n{3,}/g, '\n\n').trim() : value.replace(/\s+/g, ' ').trim();
+  if (!text) refuse(`The Task needs ${label}.`);
+  if (CONTROL.test(text)) refuse(`The Task's text holds control characters. Write ${label} as plain text.`);
+  if (text.length > max) refuse(`Write ${label} in at most ${max} characters.`);
+  return text;
+}
+export function checkProposal(raw) {
+  if (!isObject(raw)) refuse('The Task is an object with a title, a description, a goal, objectives, a priority and a severity.');
+  if (!Array.isArray(raw.objectives) || raw.objectives.length < 1 || raw.objectives.length > TASK_LIMITS.objectives) refuse(`A Task has 1 to ${TASK_LIMITS.objectives} objectives.`);
+  if (!PRIORITIES.includes(raw.priority)) refuse(`A Task's priority is one of: ${PRIORITIES.join(', ')}.`);
+  if (!SEVERITIES.includes(raw.severity)) refuse(`A Task's severity is one of: ${SEVERITIES.join(', ')}.`);
+  return {
+    title: words(raw.title, TASK_LIMITS.title, 'a title of one line'), description: words(raw.description, TASK_LIMITS.description, 'a description', { lines: true }), goal: words(raw.goal, TASK_LIMITS.goal, 'a goal'),
+    objectives: raw.objectives.map(row => words(row, TASK_LIMITS.objective, 'each objective as one line')), priority: raw.priority, severity: raw.severity,
+  };
+}
+// Subtasks are the model's own business: a row that does not read is left out, never refused.
+function readSubtasks(value) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, TASK_LIMITS.subtasks).flatMap(row => { const text = typeof row?.text === 'string' ? row.text.replace(/\s+/g, ' ').trim().slice(0, TASK_LIMITS.subtask) : ''; return text && !CONTROL.test(text) ? [{ text, state: STEPS.includes(row.state) ? row.state : 'todo' }] : []; })
+    .map((row, index) => ({ id: `s${index + 1}`, ...row }));
+}
+
+// The fields a reply carries, added to the schema every vendor is already given. Only
+// constructs the result schema already uses: a list of objects, strings, enums.
+// propose: the reply may hold a Task (a list of one, or empty). progress: it reports
+// subtasks and the objectives that are met.
+const TASK_SCHEMA = () => ({ type: 'object', additionalProperties: false, properties: {
+  title: { type: 'string', maxLength: TASK_LIMITS.title }, description: { type: 'string', maxLength: TASK_LIMITS.description }, goal: { type: 'string', maxLength: TASK_LIMITS.goal },
+  objectives: { type: 'array', maxItems: TASK_LIMITS.objectives, items: { type: 'string', maxLength: TASK_LIMITS.objective } }, priority: { type: 'string', enum: [...PRIORITIES] }, severity: { type: 'string', enum: [...SEVERITIES] },
+}, required: ['title', 'description', 'goal', 'objectives', 'priority', 'severity'] });
+export function planSchema(schema, { propose = false, progress = false } = {}) {
+  if (propose) { schema.properties.task = { type: 'array', maxItems: 1, items: TASK_SCHEMA() }; schema.required.push('task'); }
+  if (progress) {
+    schema.properties.subtasks = { type: 'array', maxItems: TASK_LIMITS.subtasks, items: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', maxLength: TASK_LIMITS.subtask }, state: { type: 'string', enum: [...STEPS] } }, required: ['text', 'state'] } };
+    schema.properties.objectivesMet = { type: 'array', maxItems: TASK_LIMITS.objectives, items: { type: 'integer' } };
+    schema.required.push('subtasks', 'objectivesMet');
+  }
+  return schema;
+}
+// Takes the Task fields off a reply before the result's own check, which accepts no other
+// key. strict: a Task that does not read is refused, so the model is asked for it once
+// more; the second time it is left out and the reply is kept as a plain answer.
+export function readPlanReply(value, { propose = false, progress = false, strict = true } = {}) {
+  if (!isObject(value)) return { rest: value, reply: null };
+  const { task, subtasks, objectivesMet, ...rest } = value, reply = {};
+  const given = Array.isArray(task) ? task : task == null ? [] : [task];
+  if (propose && given.length) {
+    try { if (given.length > 1) refuse('Return one Task at most.'); reply.proposal = checkProposal(given[0]); }
+    catch (error) { if (strict) throw error; reply.unread = true; }
+  }
+  if (progress) {
+    const steps = readSubtasks(subtasks), met = Array.isArray(objectivesMet) ? [...new Set(objectivesMet.filter(row => Number.isInteger(row) && row >= 1 && row <= TASK_LIMITS.objectives))].sort((a, b) => a - b) : [];
+    if (steps.length) reply.subtasks = steps;
+    if (met.length) reply.met = met;
+  }
+  return { rest, reply: Object.keys(reply).length ? reply : null };
+}
+
+const newId = () => `t-${crypto.randomBytes(4).toString('hex')}`;
+// Records what the model proposed. A Task that already waits is replaced by this one as
+// its next revision. startedBy says who started the work: the owner, who approves it first;
+// a schedule, which has nobody to approve; or a teammate's handoff the owner chose to work
+// on. The last two are recorded as approved at once, and a Task that waits for the owner
+// stays the one on the card.
+// edit: what approval starts ({ intent, repository, bot, request }); it stays on this machine.
+export function proposeTask(repo, id, fields, { by = 'lead', startedBy = 'owner', edit = null } = {}) {
+  const now = new Date().toISOString();
+  return nameSession(repo, id, change(repo, id, rows => {
+    const waiting = waitingTask(rows), blank = { id: newId(), session: String(id), revision: 1, ...fields, state: 'proposed', startedBy, by, proposedAt: now, approvedAt: null, rejectedAt: null, doneAt: null, subtasks: [], met: [], edit };
+    if (startedBy !== 'owner') {
+      const task = { ...blank, state: 'approved', approvedAt: now, edit: null };
+      rows.splice(waiting ? rows.length - 1 : rows.length, 0, task); return task;
+    }
+    if (waiting) return Object.assign(waiting, fields, { revision: waiting.revision + 1, by, proposedAt: now, edit });
+    rows.push(blank); return blank;
+  }));
+}
+// A session is named after its approved Task, unless the owner named it (lib/state.mjs).
+// The name is cosmetic: a session that cannot take it keeps the name it shows.
+function nameSession(repo, id, task) {
+  if (task.state === 'approved') { try { titleFromTask(repo, id, task.title); } catch { /* The session keeps the name it shows. */ } }
+  return task;
+}
+export function approveTask(repo, id) {
+  return nameSession(repo, id, change(repo, id, rows => Object.assign(waitingTask(rows) ?? refuse('No Task waits for your approval in this session.'), { state: 'approved', approvedAt: new Date().toISOString() })));
+}
+export function rejectTask(repo, id) {
+  return change(repo, id, rows => Object.assign(waitingTask(rows) ?? refuse('No Task waits for your approval in this session.'), { state: 'rejected', rejectedAt: new Date().toISOString() }));
+}
+// What may leave this machine or be shown to someone else: the Task and its progress,
+// never edit, which names a repository path and the owner's own message.
+export const sharedTask = task => task ? { id: task.id, session: task.session, revision: task.revision, title: task.title, description: task.description, goal: task.goal, objectives: [...task.objectives], priority: task.priority, severity: task.severity,
+  state: task.state, startedBy: task.startedBy, by: task.by, proposedAt: task.proposedAt, approvedAt: task.approvedAt, rejectedAt: task.rejectedAt, doneAt: task.doneAt, subtasks: task.subtasks.map(({ id, text, state }) => ({ id, text, state })), met: [...task.met] } : null;
+// The approved Task whose work has not started yet, or null.
+export function taskToStart(repo, id) {
+  const task = openTask(sessionTasks(repo, id));
+  return task?.edit && task.edit.started !== true ? task : null;
+}
+export function markStarted(repo, id) {
+  return change(repo, id, rows => { const task = openTask(rows); if (task?.edit) task.edit.started = true; return task; });
+}
+// What the model reports while it works. The goal and the objectives are not among the
+// fields a report can carry.
+export function reportProgress(repo, id, { subtasks, met } = {}) {
+  if (!subtasks && !met) return null;
+  return change(repo, id, rows => {
+    const task = openTask(rows); if (!task) return null;
+    if (subtasks) task.subtasks = subtasks;
+    if (met) task.met = met.filter(row => row <= task.objectives.length);
+    return task;
+  });
+}
+// A finished Task opens again when the owner sends more work inside its goal.
+export function reopenTask(repo, id) {
+  return change(repo, id, rows => { const task = rows.at(-1); if (task?.state === 'done') Object.assign(task, { state: 'approved', doneAt: null }); return task ?? null; });
+}
+// Done: the model reports every objective met, and the turn that did the work has ended.
+export function finishTask(repo, id) {
+  const open = openTask(sessionTasks(repo, id));
+  if (!open || open.met.length < open.objectives.length) return null;
+  return change(repo, id, rows => { const task = openTask(rows); if (task && task.met.length >= task.objectives.length) Object.assign(task, { state: 'done', doneAt: new Date().toISOString() }); return task; });
+}
+
+// The same at the end of a turn, where a Task that cannot be closed never fails the turn.
+export function closeTask(repo, id) { try { return finishTask(repo, id); } catch { return null; } }
+
+// What one turn is told about Tasks and may return. first: the turn that answers a
+// message; work: an editing turn, which reports progress and proposes nothing.
+// covered: the session has a Task the owner approved, so work inside its goal may go on.
+// unattended: what started the turn when its Task waits for nobody (schedule or handoff), else false.
+export function turnPlan(repo, id, { work = false, unattended = false } = {}) {
+  const rows = sessionTasks(repo, id), open = openTask(rows), last = rows.at(-1) ?? null;
+  if (work) return open ? { propose: false, progress: true, work: true, open } : null;
+  const agreed = open ?? (last?.state === 'done' ? last : null);
+  return { propose: true, progress: Boolean(agreed), waiting: waitingTask(rows), open: agreed, covered: Boolean(agreed), unattended };
+}
+const shown = task => ({ title: task.title, description: task.description, goal: task.goal, objectives: task.objectives.map((text, index) => `${index + 1}. ${text}`), priority: task.priority, severity: task.severity, state: task.state, revision: task.revision, subtasks: task.subtasks.map(({ text, state }) => ({ text, state })), objectivesMet: task.met });
+const FIELDS = 'a title (one line), a description of the work, the goal, the objectives that say when it is done (one line each), a priority (urgent, high, medium or low) and a severity (critical, high, medium or low)';
+const PROGRESS = 'Break the work into subtasks as you see fit and change them freely; they need no approval. Put the list as it stands in subtasks, each todo, doing or done, or leave subtasks empty to keep the list as it is. In objectivesMet give the numbers of the objectives that are met now.';
+// The rule as every vendor's model is told it. What ELU Code enforces is the gate in
+// ProjectController.ask: an editing turn starts only for an approved Task.
+export function planPrompt(plan) {
+  if (!plan) return [];
+  if (plan.work) return [`The owner approved the Task below, and this turn does its work. Meet every objective. ${PROGRESS} The goal and the objectives are the owner's: if one has to change, stop, return outcome needs_input and say what should change.`, dataBlock('Approved Task', shown(plan.open))];
+  const parts = [`Plan first. When the owner asks for a change to code or files, or for work that needs planning, change nothing in this turn: read what you need, then put one Task in task with ${FIELDS}, and say in the summary what you found and how you would do it. ${plan.unattended === 'handoff' ? 'The owner chose to work on this handoff from a teammate: the Task is recorded as started by handoff and the work goes on.' : plan.unattended ? 'A schedule started this turn and nobody is there to approve: the Task is recorded as started by schedule and the work goes on.' : 'The owner approves or rejects the Task, and the work starts only after they approve.'} When you must ask the owner something before you can write the Task, ask it and leave task empty; the Task comes with a later reply. A question, an explanation or a greeting gets a plain answer and an empty task list.`];
+  if (plan.waiting) parts.push('The Task below waits for the owner\'s approval. When their message asks for changes to it, return the whole Task again in task, revised. When it only asks about it, answer and leave task empty: the Task stays as it is. Only the owner approves it, with a key; do not start its work.', dataBlock('Task waiting for approval', shown(plan.waiting)));
+  else if (plan.open) parts.push(`The owner approved the Task below. Work inside its goal needs no new Task: leave task empty. A new piece of work needs a Task of its own in task. To change the goal or an objective, return the whole revised Task in task; it needs the owner's approval again. ${PROGRESS}`, dataBlock('Approved Task', shown(plan.open)));
+  return parts;
+}
+export const NEEDS_TASK = `A request that changes files needs a Task first. Change nothing, set intent to edit, and put one Task in task with ${FIELDS}.`;
+const NO_TASK = 'No Task was read from this reply, so nothing was changed. Send your request again.';
+const STILL_WAITS = 'The Task still waits for your approval, so nothing was changed.';
+const asAnswer = (response, line) => { response.intent = 'answer'; delete response.repository; if (line) response.summary = `${response.summary.slice(0, 3800)}\n\n${line}`; };
+// What a first turn's reply does to the session's Tasks. Returns held when the reply
+// must not start an edit: a Task now waits for the owner, or none was read. The reply is
+// then kept as an answer, so the session rests where an answer leaves it.
+// message: the owner's request. by: who answered, lead or @name. bot: the working bot that would make the edit.
+export function settleReply(repo, task, response, { plan, message, by = 'lead', bot = null } = {}) {
+  const reply = response.plan ?? null; delete response.plan;
+  const edit = response.intent === 'edit' && response.outcome === 'done';
+  // A reply that asks the owner something first proposes nothing yet: its Task comes with the answer.
+  const proposal = response.outcome === 'done' ? reply?.proposal ?? null : null;
+  if (reply?.subtasks || reply?.met) reportProgress(repo, task.id, reply);
+  if (proposal) {
+    if (plan.unattended) { proposeTask(repo, task.id, proposal, { by, startedBy: plan.unattended === 'handoff' ? 'handoff' : 'schedule' }); return null; }
+    proposeTask(repo, task.id, proposal, { by, edit: { intent: response.intent, repository: response.repository ?? null, bot, request: message, started: false } });
+    if (edit) asAnswer(response);
+    return 'held';
+  }
+  if (!edit) return null;
+  if (plan.waiting) { asAnswer(response, STILL_WAITS); return 'held'; }
+  if (plan.covered) { reopenTask(repo, task.id); return null; }
+  asAnswer(response, NO_TASK); return 'held';
+}
+// What an editing turn's reply reports. Returns the reply without the Task fields.
+export function settleWork(repo, id, result) {
+  const reply = result?.plan ?? null;
+  if (result) delete result.plan;
+  if (reply) { try { reportProgress(repo, id, reply); } catch { /* A report that cannot be kept never fails the work. */ } }
+  return result;
+}
+// The owner's own short yes, typed instead of the key.
+export const saysYes = text => /^(y|yes|ok|okay|approve|approved|go|go ahead|do it|lgtm)[.! ]*$/i.test(String(text ?? '').trim());

package/lib/policy.mjs

@@ -0,0 +1,98 @@
+import path from 'node:path';
+import os from 'node:os';
+import fs from 'node:fs';
+import { refuse, relativePath, within } from './util.mjs';
+import { CAPS, ENFORCEMENT, VENDOR_NAMES } from './vendors.mjs';
+import { PROFILES } from './modes.mjs';
+
+const INTERPRETERS = new Set(['node', 'nodejs', 'deno', 'bun', 'python', 'python2', 'python3', 'ruby', 'perl', 'php', 'lua', 'bash', 'sh', 'zsh', 'fish', 'dash', 'ksh', 'csh', 'tcsh', 'osascript', 'tsx', 'ts-node', 'awk', 'gawk']);
+const RUNNERS = new Set(['npx', 'pnpx', 'bunx', 'env', 'xargs', 'eval', 'exec', 'source', '.', 'sudo', 'su', 'doas', 'nohup', 'timeout', 'nice', 'time', 'watch', 'command', 'builtin', 'make', 'docker', 'ssh', 'script', 'expect', 'parallel', 'find']);
+const NETWORK = new Set(['curl', 'wget', 'http', 'https', 'nc', 'ncat', 'telnet', 'scp', 'sftp', 'ftp', 'rsync']);
+const GIT_READS = new Set(['log', 'show', 'diff', 'status', 'blame', 'grep', 'rev-parse', 'ls-files', 'ls-tree', 'describe', 'shortlog', 'cat-file', 'rev-list', 'merge-base', 'name-rev']);
+export function allowRuleProblem(rule) {
+  if (typeof rule !== 'string' || !rule.trim()) return 'an empty rule';
+  if (rule.length > 300 || /[\r\n]/.test(rule)) return 'a rule must fit on one line, within 300 characters';
+  if (!/^[A-Za-z][A-Za-z0-9_]*(\([^\r\n]+\))?$/.test(rule)) return 'not a tool permission rule';
+  if (/^Bash(\(\s*(\*|:\*)?\s*\))?$/.test(rule)) return 'it allows every shell command';
+  return null;
+}
+export function allowRuleRisk(rule) {
+  const match = /^Bash\((.*)\)$/.exec(rule);
+  if (!match) return null;
+  const prefix = match[1].replace(/(?::\*|\s+\*)$/, '').trim();
+  const [first, ...rest] = prefix.split(/\s+/);
+  const program = path.basename(first);
+  if (RUNNERS.has(program) || INTERPRETERS.has(program)) return { level: 'any', text: `${program} can run arbitrary code.` };
+  if (['npm', 'pnpm', 'yarn'].includes(program)) {
+    if ((rest[0] === 'run' || rest[0] === 'run-script') && /^[a-zA-Z0-9:_-]+$/.test(rest[1] ?? '') && rest.length === 2) return null;
+    if (rest.length === 1 && ['test', 't'].includes(rest[0])) return null;
+    return { level: 'any', text: 'Name one package script; package runners and installs are refused.' };
+  }
+  if (NETWORK.has(program)) return { level: 'changes', text: 'It reaches another machine.' };
+  if (program === 'git' && GIT_READS.has(rest[0]) && rest.length === 1) return null;
+  return { level: 'broad', text: 'This command prefix has not been tested.' };
+}
+export function commandRule(command) {
+  if (typeof command !== 'string' || !/^[a-zA-Z0-9_-]+(?: [a-zA-Z0-9:_-]+)*$/.test(command)) refuse('Allowed commands must be plain program and argument prefixes, without shell syntax.');
+  const rule = `Bash(${command}:*)`;
+  const problem = allowRuleProblem(rule); const risk = allowRuleRisk(rule);
+  if (problem || risk) refuse(`Cannot allow ${command}: ${problem ?? risk.text}`, { risk: risk?.level });
+  return rule;
+}
+export function sensitive(file) {
+  return /(^|\/)(?:\.env(?:\..*)?|\.npmrc|\.netrc|\.pypirc|credentials(?:\.json)?|auth\.json|id_(?:rsa|ed25519)|[^/]+\.pem)$/.test(file);
+}
+// Dependency files stay protected in locked and ask; Approve for me and Full access may change them.
+const DEPENDENCY = /(^|\/)(?:package\.json|package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|[^/]*\.lock)$/;
+const dependenciesOpen = mode => ['auto', 'full'].includes(mode);
+export function protectedPath(file, { mode = 'locked' } = {}) {
+  return /(^|\/)(?:\.elu-code|\.git|\.github|\.gitlab|\.circleci|\.claude|\.codex|\.agents|\.gemini|\.cursor|\.vscode|\.idea|\.zed|\.husky|\.githooks|node_modules)(\/|$)/.test(file)
+    || /(^|\/)(?:\.yarnrc\.yml|\.pnpmfile\.cjs|pnpm-workspace\.yaml|bunfig\.toml|\.mocharc[^/]*|vitest\.workspace[^/]*|ava\.config[^/]*|karma\.conf[^/]*|\.nycrc[^/]*|pyproject\.toml|setup\.cfg|tox\.ini|pytest\.ini|conftest\.py)$/.test(file)
+    || /(^|\/)(?:AGENTS(?:\.override)?\.md|CLAUDE(?:\.local)?\.md|\.mcp\.json|\.gitmodules|\.gitattributes|\.gitignore|\.npmrc|Jenkinsfile|Makefile|Dockerfile)$/.test(file)
+    || (!dependenciesOpen(mode) && DEPENDENCY.test(file))
+    || /(^|\/)(?:(?:vitest|vite|jest|webpack|rollup|babel|next|eslint|prettier|playwright|cypress|tsup)\.config\.[^/]+|tsconfig[^/]*\.json|\.babelrc[^/]*|\.eslintrc[^/]*)$/.test(file);
+}
+export function protectedFiles(files, { mode = 'locked' } = {}) {
+  return [...new Set(['.elu-code', '.git', '.github', '.gitlab', '.circleci', '.claude', '.codex', '.agents', '.gemini', '.cursor', '.vscode', '.idea', '.zed', '.husky', '.githooks', 'node_modules', 'AGENTS.md', 'AGENTS.override.md', 'CLAUDE.md', 'CLAUDE.local.md', '.mcp.json', '.gitignore', '.gitattributes', '.gitmodules', ...files.filter((x) => protectedPath(x, { mode }) || (!dependenciesOpen(mode) && /(^|\/)package\.json$/.test(x)))])];
+}
+// What enforces each rule for this role in this profile, from the vendor table. A reviewer
+// set to auto or none reports like Codex, the vendor it may become.
+export function policyReport(role, { mode = 'locked' } = {}) {
+  if (!PROFILES.includes(mode)) refuse('Choose ask, auto, or full.');
+  const table = ENFORCEMENT[['auto', 'none'].includes(role.vendor) ? 'codex' : role.vendor] ?? {};
+  const rules = (table[mode] ?? table.locked ?? []).map(({ rule, enforcement }) => ({ rule, enforcement: typeof enforcement === 'function' ? enforcement(role) : enforcement }));
+  return { vendor: role.vendor, access: role.access, rules };
+}
+// What a role may ask of its vendor, from CAPS. mode is the session profile: an edit role
+// on a vendor without lockedEdit runs only in a mode that lifts the lock.
+export function assertPolicy(role, { mode = 'locked' } = {}) {
+  const caps = CAPS[role.vendor];
+  if (!caps) refuse(`Choose a supported vendor: ${role.vendor}.`);
+  if (!PROFILES.includes(mode)) refuse('Choose ask, auto, or full.');
+  if (role.network !== 'off') refuse("Network comes from the session's permissions.");
+  for (const command of role.commands) commandRule(command);
+  const name = VENDOR_NAMES[role.vendor];
+  if (!caps.commands && role.commands.length) refuse(`${name} cannot enforce a per-run command allow-list. Remove the allowed commands, or choose Claude.`);
+  if (!caps.budget && role.maxCostUsd !== null) refuse(`${name} cannot enforce a dollar budget. Set maxCostUsd to null and use the time limit, or choose Claude.`);
+  if (mode === 'locked' && !caps.lockedEdit && role.access !== 'read') refuse(`${name} cannot edit in Read only. Choose Ask for approval, Approve for me, or Full access.`);
+  if (caps.model === 'none' && role.model !== undefined) refuse(`${name} does not take a model name.`);
+  if (caps.model === 'required' && !role.model) refuse(`${name} needs a model name.`);
+  if (role.access === 'read' && role.commands.length) refuse('A read-only run uses file tools or supplied source context, without shell commands.');
+  if (role.access === 'edit' && !role.writablePaths.length) refuse('Editing needs writable paths.');
+  if (role.vendor === 'claude' && role.commands.length && (role.writablePaths.length !== 1 || role.writablePaths[0] !== '.')) refuse('Claude shell access with narrower writable paths has not been tested. Use no shell commands or allow the worktree.');
+  for (const p of role.writablePaths) relativePath(p);
+  return role;
+}
+export function assertNoCodexProjectConfig(cwd) {
+  const home = os.homedir();
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    if (dir !== home && fs.existsSync(path.join(dir, '.codex', 'config.toml'))) refuse('Codex project configuration could add MCP servers. Move it out of this task before running.');
+    if (dir === path.dirname(dir)) break;
+  }
+  for (const file of ['/etc/codex/config.toml', '/etc/codex/managed_config.toml', '/etc/codex/requirements.toml', '/Library/Application Support/com.openai.codex/config.toml', '/Library/Application Support/com.openai.codex/managed_config.toml']) {
+    if (fs.existsSync(file)) refuse('Managed Codex configuration has not passed the no-MCP tests.');
+  }
+}
+export function pathAllowed(file, paths) {
+  return paths.some((p) => p === '.' || within(path.resolve('/', p), path.resolve('/', file)));
+}

package/lib/process.mjs

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { atomic, noSymlinks, personalDirectory, refuse, within } from './util.mjs';
+
+export function killGroup(pid, signal = 'SIGTERM') {
+  if (!Number.isInteger(pid) || pid < 2) return;
+  try { process.kill(-pid, signal); } catch { /* The process group already ended. */ }
+}
+let own = null;
+export function processIdentity(pid) {
+  if (!Number.isInteger(pid) || pid < 2) return null;
+  if (pid === process.pid && own?.pid === pid) return own.identity;
+  const r = spawnSync('ps', ['-p', String(pid), '-o', 'lstart=', '-o', 'command='], { encoding: 'utf8' });
+  const identity = r.status === 0 ? r.stdout.trim() : null;
+  if (pid === process.pid && identity) own = { pid, identity };
+  return identity;
+}
+export function recoverProcess(record) {
+  if (!record?.pid || !record.identity) return 'interrupted';
+  if (processIdentity(record.pid) !== record.identity) return 'interrupted';
+  killGroup(record.pid, 'SIGKILL');
+  return 'stopped';
+}
+// Claude Code installs to ~/.local/bin, and Debian and Ubuntu put that folder on PATH only in
+// login shells. ELU Code started by tmux, ssh, launchd or systemd would not find the lead. The
+// folder is appended, so anything earlier on PATH still wins. Every process ELU Code starts
+// (conductor, peer daemon, agent runs) inherits it.
+export function addUserBin(env = process.env, home = os.homedir()) {
+  const folder = path.join(home, '.local', 'bin'), parts = (env.PATH ?? '').split(path.delimiter).filter(Boolean);
+  if (!path.isAbsolute(folder) || parts.includes(folder)) return false;
+  try { if (!fs.statSync(folder).isDirectory()) return false; } catch { return false; }
+  env.PATH = [...parts, folder].join(path.delimiter); return true;
+}
+// The environment an agent gets: a fixed allow-list, plus a vendor's own named keys
+// (meta.envKeys) and overrides it sets, such as a private HOME under ELU Code's state.
+const KEPT = /^(PATH|HOME|USER|LOGNAME|LANG|LC_ALL|LC_CTYPE|TERM|SHELL|TMPDIR|CODEX_HOME|CLAUDE_CONFIG_DIR|XDG_CONFIG_HOME|XDG_RUNTIME_DIR|SSL_CERT_FILE|SSL_CERT_DIR)$/;
+const NAME = /^[A-Z][A-Z0-9_]{1,63}$/;
+export function agentEnv(env = process.env, extraKeys = [], overrides = {}) {
+  if (!Array.isArray(extraKeys) || extraKeys.some(key => !NAME.test(key))) refuse('Extra environment names must be upper-case words.');
+  const result = Object.fromEntries(Object.entries(env).filter(([key]) => KEPT.test(key) || extraKeys.includes(key)));
+  for (const [key, value] of Object.entries(overrides)) {
+    if (!NAME.test(key) || typeof value !== 'string' || /[\x00-\x1f]/.test(value)) refuse('Environment overrides must be upper-case names with plain text values.');
+    if (key === 'HOME' && (!path.isAbsolute(value) || !within(path.resolve(personalDirectory()), path.resolve(value)))) refuse("A private HOME must be inside ELU Code's personal directory.");
+    result[key] = value;
+  }
+  return result;
+}
+// hold: while it returns true (an approval is waiting for the owner) the role
+// time limit does not advance; the output limit and abort still apply.
+export async function runProcess({ bin, args, cwd, env, input, logFile, processFile, timeoutSeconds, onStart, signal, hold = null }) {
+  signal?.throwIfAborted();
+  noSymlinks(logFile);
+  const fd = fs.openSync(logFile, 'wx', 0o600);
+  const stderrFile = `${logFile}.stderr`;
+  noSymlinks(stderrFile);
+  const stderrFd = fs.openSync(stderrFile, 'wx', 0o600);
+  let child;
+  try { child = spawn(bin, args, { cwd, env, detached: true, stdio: ['pipe', fd, stderrFd] }); }
+  finally { fs.closeSync(fd); fs.closeSync(stderrFd); }
+  if (child.pid) {
+    const record = { pid: child.pid, identity: processIdentity(child.pid), bin: path.basename(bin) };
+    if (processFile) atomic(processFile, record);
+    onStart?.(record);
+  }
+  let timedOut = false;
+  let outputLimit = false;
+  const expire = () => { timedOut = true; killGroup(child.pid, 'SIGKILL'); };
+  let elapsed = 0, last = Date.now();
+  const held = () => { try { return hold() === true; } catch { return false; } };
+  const timer = hold ? setInterval(() => { const now = Date.now(); if (!held()) elapsed += now - last; last = now; if (elapsed >= timeoutSeconds * 1000) { clearInterval(timer); expire(); } }, 250) : setTimeout(expire, timeoutSeconds * 1000);
+  const outputTimer = setInterval(() => {
+    if (fs.statSync(logFile).size + fs.statSync(stderrFile).size > 16 * 1024 * 1024) { outputLimit = true; killGroup(child.pid, 'SIGKILL'); }
+  }, 500);
+  const stop = () => killGroup(child.pid, 'SIGKILL');
+  signal?.addEventListener('abort', stop, { once: true });
+  if (signal?.aborted) stop();
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, stop);
+  child.stdin.on('error', () => {});
+  child.stdin.end(input ?? '');
+  const result = await new Promise((resolve) => {
+    child.once('error', (error) => resolve({ code: null, error: error.message }));
+    child.once('close', (code, signal) => resolve({ code, signal }));
+  });
+  clearTimeout(timer); clearInterval(timer); clearInterval(outputTimer); stop();
+  signal?.removeEventListener('abort', stop);
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.off(signal, stop);
+  if (processFile) atomic(processFile, { pid: null, identity: null });
+  signal?.throwIfAborted();
+  return { ...result, timedOut, outputLimit, stderrFile };
+}

package/lib/project-settings.mjs

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { atomic, dataBlock, noSymlinks, refuse } from './util.mjs';
+import { clipNotes } from './memory.mjs';
+import { approveRemoved, approveSaved, approvedAsItStands, trustedText } from './project-trust.mjs';
+
+// A project's instructions and context, written by the owner in the Projects tab and kept
+// in .elu-code/ beside the project's settings, so a team shares them through Git. Every
+// lead turn gets them (projectPromptParts) once the owner approved their text on this
+// machine: a save here approves what it writes, and text that arrived any other way is
+// asked about first (lib/project-trust.mjs). Each file is at most 100 KB; a bigger save is
+// refused with one line.
+export const LIMIT = 100 * 1024;
+const settingsDir = root => path.join(root, '.elu-code');
+const settingsFile = (root, name) => path.join(settingsDir(root), name);
+
+// Text as the owner typed it, with Windows line ends and control characters taken out.
+function checkText(value, label) {
+  const text = String(value ?? '').replace(/\r\n?/g, '\n').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+  if (Buffer.byteLength(withNewline(text)) > LIMIT) refuse(`Keep ${label} under 100 KB.`);
+  return text;
+}
+const withNewline = text => text.endsWith('\n') ? text : `${text}\n`;
+// Empty text means he goes without: nothing stays in force, and the tab shows none again.
+// The file is removed only when it is the text he approved; one that is not in use is not
+// his text to clear, so it stays and is asked about.
+function saveText(root, name, value, label) {
+  const text = checkText(value, label), file = settingsFile(root, name); noSymlinks(file);
+  if (!text.trim()) {
+    const mine = approvedAsItStands(root, name);
+    if (mine || trustedText(root, name) != null) approveRemoved(root, name);
+    if (mine) fs.unlinkSync(file);
+    return '';
+  }
+  approveSaved(root, name, withNewline(text)); atomic(file, withNewline(text)); return text;
+}
+export function saveInstructions(root, text) { return saveText(root, 'instructions.md', text, 'the instructions'); }
+export function saveContext(root, text) { return saveText(root, 'context.md', text, 'the context'); }
+
+// The text in force, which is what the Projects tab shows and edits: the file's when he
+// approved it as it stands, else the text he approved last. A file he has not approved is
+// never carried into the editor, so a save is his own text. With nothing in force it reads
+// as empty; a symbolic link on the way is refused.
+export function readProjectSettings(root) {
+  return { instructions: trustedText(root, 'instructions.md') ?? '', context: trustedText(root, 'context.md') ?? '' };
+}
+// What a lead turn gets after its instructions: the owner's instructions to follow and the
+// context as data, each only as the owner approved it on this machine. Long text is
+// clipped the way Claude Code memory is.
+export function projectPromptParts(root) {
+  const { instructions, context } = readProjectSettings(root), parts = [];
+  if (instructions.trim()) parts.push(`Project instructions (owner):\n${clipNotes(instructions)}`);
+  if (context.trim()) parts.push(dataBlock('Project context', clipNotes(context)));
+  return parts;
+}