@worca/app 1.4.0 → 1.5.0-rc.3

package/src/core/model-env.mjs

@@ -58,6 +58,30 @@ export function withTierModelEnv(env, modelId) {
   return out;
 }
 
+// The CLI's cloud transports. Any one truthy makes the CLI ignore
+// ANTHROPIC_BASE_URL and talk to that cloud instead (Vertex: ANTHROPIC_VERTEX_BASE_URL),
+// so a shell that exports CLAUDE_CODE_USE_VERTEX=1 for its first-party Claude
+// sent every bridged or endpoint-routed model there — an id the cloud does not
+// know (`unrecognized_model`, exit 1). The model env merges over the ambient env
+// at spawn, so an explicit '0' (the CLI reads it as false) wins.
+export const PROVIDER_MODE_ENV_KEYS = Object.freeze([
+  'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_FOUNDRY',
+]);
+
+/**
+ * An endpoint-routed env with every cloud transport the entry left unset
+ * turned off. Pure: a non-routed env (no ANTHROPIC_BASE_URL) comes back
+ * untouched and an explicit key in the env is never overwritten.
+ * @param {Record<string,string>|undefined} env  a PREPARED model env
+ * @returns {Record<string,string>|undefined}
+ */
+export function withProviderModesOff(env) {
+  if (!env || typeof env !== 'object' || !('ANTHROPIC_BASE_URL' in env)) return env;
+  const out = { ...env };
+  for (const k of PROVIDER_MODE_ENV_KEYS) if (!(k in out)) out[k] = '0';
+  return out;
+}
+
 // Env keys a model entry may NOT set (§4.4): process fundamentals and worca's
 // own runtime knobs, any of which injection could otherwise subvert (mock
 // mode, the claude binary path, the effort flag name). Everything else —
@@ -291,7 +315,7 @@ export function subagentModelIssue(v) {
 // catalog (settings.mjs) and a plugin manifest (plugin-manifest.mjs) validate
 // the same shape against one rule, and neither may import the other.
 //
-//   { provider: 'copilot'|'openai'|'anthropic', api: 'anthropic'|'openai-chat',
+//   { provider: 'copilot'|'openai'|'anthropic', api: 'anthropic'|'openai-chat'|'openai-responses',
 //     model: '<upstream id>', baseUrl?, apiKey?, headers?, capabilities? }
 //
 // A bridged entry is dispatched through worca's in-process loopback bridge
@@ -301,13 +325,17 @@ export function subagentModelIssue(v) {
 // not also appear in the entry's own `env` map.
 
 export const UPSTREAM_PROVIDERS = Object.freeze(['copilot', 'openai', 'anthropic']);
-export const UPSTREAM_APIS = Object.freeze(['anthropic', 'openai-chat']);
+export const UPSTREAM_APIS = Object.freeze(['anthropic', 'openai-chat', 'openai-responses']);
 /** Which wire protocols each provider can be driven through. */
 export const PROVIDER_APIS = Object.freeze({
-  copilot: Object.freeze(['anthropic', 'openai-chat']),
-  openai: Object.freeze(['openai-chat']),
+  copilot: Object.freeze(['anthropic', 'openai-chat', 'openai-responses']),
+  openai: Object.freeze(['openai-chat', 'openai-responses']),
   anthropic: Object.freeze(['anthropic']),
 });
+/** The wire protocols the bridge TRANSLATES to — everything but the Anthropic passthrough. */
+export const TRANSLATED_APIS = Object.freeze(['openai-chat', 'openai-responses']);
+/** Whether `api` is translated by the bridge (no server tools, no thinking passthrough). */
+export function isTranslatedApi(api) { return TRANSLATED_APIS.includes(api); }
 /** Env keys the bridge owns; rejected in an `env` map beside `upstream`. */
 export const BRIDGE_ROUTING_KEYS = Object.freeze([
   'ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY', 'ANTHROPIC_MODEL',
@@ -316,6 +344,10 @@ export const BRIDGE_ROUTING_KEYS = Object.freeze([
 export const CAPABILITY_FLAGS = Object.freeze(['toolCalls', 'vision', 'reasoning']);
 /** Numeric capability limits an entry may pin. */
 export const CAPABILITY_LIMITS = Object.freeze(['maxPromptTokens', 'maxOutputTokens']);
+/** Reasoning-effort levels an upstream may list, lowest first (capabilities.reasoningEfforts). */
+export const REASONING_EFFORT_LEVELS = Object.freeze(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+/** List-valued capabilities an entry may pin. */
+export const CAPABILITY_LISTS = Object.freeze(['reasoningEfforts']);
 const FORBIDDEN_UPSTREAM_HEADERS = new Set(['authorization', 'host', 'content-length', 'content-type', 'transfer-encoding']);
 const HEADER_NAME_RE = /^[A-Za-z0-9-]{1,80}$/;
 
@@ -334,8 +366,16 @@ export function assertModelCapabilities(caps) {
       const n = Number(v);
       if (!Number.isInteger(n) || n <= 0) throw new Error(`upstream.capabilities.${k} must be a positive integer`);
       out[k] = n;
+    } else if (CAPABILITY_LISTS.includes(k)) {
+      if (v === null || v === undefined) continue;
+      if (!Array.isArray(v)) throw new Error(`upstream.capabilities.${k} must be an array of effort levels`);
+      for (const e of v) {
+        if (!REASONING_EFFORT_LEVELS.includes(e)) throw new Error(`upstream.capabilities.${k}: unknown level ${JSON.stringify(e)} — allowed: ${REASONING_EFFORT_LEVELS.join(', ')}`);
+      }
+      const levels = REASONING_EFFORT_LEVELS.filter((e) => v.includes(e));
+      if (levels.length) out[k] = levels;
     } else {
-      throw new Error(`unknown upstream.capabilities key ${JSON.stringify(k)} — allowed: ${[...CAPABILITY_FLAGS, ...CAPABILITY_LIMITS].join(', ')}`);
+      throw new Error(`unknown upstream.capabilities key ${JSON.stringify(k)} — allowed: ${[...CAPABILITY_FLAGS, ...CAPABILITY_LIMITS, ...CAPABILITY_LISTS].join(', ')}`);
     }
   }
   return Object.keys(out).length ? out : undefined;
@@ -422,9 +462,9 @@ export function upstreamEnvConflict(env) {
   return null;
 }
 
-/** Whether an `openai-chat` upstream drops the CLI's web tools (§5.3). */
+/** The CLI's web tools a translated (openai-chat / openai-responses) upstream withholds (§5.3). */
 export function bridgeExcludedTools(upstream) {
-  return upstream && upstream.api === 'openai-chat' ? ['WebSearch', 'WebFetch'] : [];
+  return upstream && isTranslatedApi(upstream.api) ? ['WebSearch', 'WebFetch'] : [];
 }
 
 // ── providers: account-level state shared by bridged entries (§6.2) ─────────

package/src/core/model-test.mjs

@@ -9,6 +9,7 @@ import { runClaude } from './claude-runner.mjs';
 import { resolveModelEnv } from './config.mjs';
 import { AUX_EFFORT } from './model-env.mjs';
 import { classifyError } from './recoverable-error.mjs';
+import { bridgeEvents } from './bridge/telemetry.mjs';
 
 const TEST_TIMEOUT_MS = 60_000;
 const REPLY_CAP = 100;
@@ -56,6 +57,17 @@ export async function testModel(id, { signal, bin, run = runClaude } = {}) {
   }
   const timer = setTimeout(() => ctrl.abort(), TEST_TIMEOUT_MS);
   timer.unref?.();
+  // A bridged model's failure is recorded by the in-process bridge with the
+  // upstream's reason; the CLI's stderr for such a run carries only warnings
+  // (unrecognized_model, connectors disabled), so that reason wins. The test's
+  // own call is untagged (resolveModelEnv(id) passes no execution id); a
+  // pipeline node run on the same model is tagged and ignored. An untagged
+  // call (Ask, titles) failing on the same id during the Test is picked up
+  // too — rare, and still a real failure of this model.
+  const want = String(id || '').toLowerCase();
+  let bridgeFailure = null;
+  const onBridgeFailure = (e) => { if (e && !e.tag && String(e.catalogId || '').toLowerCase() === want) bridgeFailure = e; };
+  bridgeEvents.on('failure', onBridgeFailure);
   try {
     const { text } = await run({
       cwd: process.cwd(),
@@ -76,17 +88,29 @@ export async function testModel(id, { signal, bin, run = runClaude } = {}) {
     }
     return { ok: true, text: reply.slice(0, REPLY_CAP) };
   } catch (err) {
-    if (err && err.name === 'AbortError') {
+    // The Test's own timer can fire while the CLI still retries a failure the
+    // bridge booked (it retries a 5xx well past TEST_TIMEOUT_MS): that failure
+    // is the answer. A Test the caller cancelled stays a timeout.
+    const booked = bridgeFailure && bridgeFailure.message && !(signal && signal.aborted);
+    if (err && err.name === 'AbortError' && !booked) {
       return { ok: false, errorClass: 'timeout', message: `Timed out after ${TEST_TIMEOUT_MS / 1000}s`, hint: hintFor('timeout') };
     }
-    const message = err && err.message ? err.message : String(err);
-    const errorClass = (err && err.errorClass) || classifyError(message);
+    const message = bridgeFailure && bridgeFailure.message
+      ? String(bridgeFailure.message)
+      : (err && err.message ? err.message : String(err));
+    const errorClass = bridgeFailure && bridgeFailure.message
+      ? classifyError(message)
+      : ((err && err.errorClass) || classifyError(message));
     // A bridged model whose provider is not usable (model-bridge-design.md
     // §8.5): resolveModelEnv fails fast with `bridgeReason`, and the hint
-    // names the fix instead of the generic credential advice.
-    const hint = err && err.bridgeReason ? bridgeHintFor(err.bridgeReason, err.bridgeProvider) : hintFor(errorClass);
+    // names the fix instead of the generic credential advice. A bridge failure
+    // classed `network` ("endpoint unreachable", "upstream error (500)") is not
+    // an ANTHROPIC_BASE_URL problem: no hint, so the UI shows the message.
+    const hint = err && err.bridgeReason ? bridgeHintFor(err.bridgeReason, err.bridgeProvider)
+      : bridgeFailure && bridgeFailure.message && errorClass === 'network' ? '' : hintFor(errorClass);
     return { ok: false, errorClass, message, ...(hint ? { hint } : {}) };
   } finally {
+    bridgeEvents.off('failure', onBridgeFailure);
     clearTimeout(timer);
     if (signal) signal.removeEventListener?.('abort', onOuterAbort);
   }

package/src/core/notifications.mjs

@@ -4,7 +4,10 @@
 // self-paused, completed) lands here — but the table carries a `scope` column so an
 // app-wide centre can reuse it without a second system.
 //
-// Read state is GLOBAL (Worca is single-user per machine). `info` rows arrive
+// Read state is GLOBAL on a local install (one person per machine). On a shared deployment
+// (a real per-person sign-in, identity.mjs#isSharedIdentity) callers pass `reader`, and
+// "Mark read" is per person (notification_reads, v37): a row is read for a person when it
+// was read globally (an info row, or a resolved problem) or they marked it. `info` rows arrive
 // already read: only `problem` rows count towards the unread badge. A problem
 // RESOLVES itself when the user acts on it (Run now, reschedule, resume), so stale
 // alarms never pile up.
@@ -40,9 +43,9 @@ function rowToNotification(r) {
     title: r.title || null,
     message: r.message,
     createdAt: r.created_at,
-    readAt: r.read_at || null,
+    readAt: r.read_at || r.reader_read_at || null,
     resolvedAt: r.resolved_at || null,
-    unread: !r.read_at && r.severity === 'problem',
+    unread: !r.read_at && !r.reader_read_at && r.severity === 'problem',
   };
 }
 
@@ -72,19 +75,26 @@ export function addNotification({
  * List notifications, newest first.
  * @param {{scope?:string, unread?:boolean, problems?:boolean, scheduleId?:string, limit?:number}} [o]
  */
-export function listNotifications({ scope = 'schedule', unread = false, problems = false, scheduleId = null, limit = 200 } = {}) {
-  const where = ['scope = ?'];
+export function listNotifications({ scope = 'schedule', unread = false, problems = false, scheduleId = null, limit = 200, reader = null } = {}) {
+  const where = ['n.scope = ?'];
   const args = [scope];
-  if (unread) where.push("read_at IS NULL AND severity = 'problem'");
-  if (problems) where.push("severity = 'problem'");
-  if (scheduleId) { where.push('schedule_id = ?'); args.push(scheduleId); }
+  if (unread) where.push(`n.read_at IS NULL AND n.severity = 'problem'${reader ? ' AND r.read_at IS NULL' : ''}`);
+  if (problems) where.push("n.severity = 'problem'");
+  if (scheduleId) { where.push('n.schedule_id = ?'); args.push(scheduleId); }
   const lim = Math.max(1, Math.min(1000, Number(limit) || 200));
-  return getDb().prepare(`SELECT * FROM notifications WHERE ${where.join(' AND ')} ORDER BY id DESC LIMIT ${lim}`)
-    .all(...args).map(rowToNotification);
+  const join = reader ? 'LEFT JOIN notification_reads r ON r.notification_id = n.id AND r.reader = ?' : '';
+  const cols = reader ? 'n.*, r.read_at AS reader_read_at' : 'n.*';
+  return getDb().prepare(`SELECT ${cols} FROM notifications n ${join} WHERE ${where.join(' AND ')} ORDER BY n.id DESC LIMIT ${lim}`)
+    .all(...(reader ? [reader] : []), ...args).map(rowToNotification);
 }
 
-/** Unread PROBLEM rows in a scope — the sidebar badge. */
-export function unreadCount(scope = 'schedule') {
+/** Unread PROBLEM rows in a scope — the sidebar badge (per person when `reader` is given). */
+export function unreadCount(scope = 'schedule', { reader = null } = {}) {
+  if (reader) {
+    return getDb().prepare(`SELECT COUNT(*) AS n FROM notifications n
+      LEFT JOIN notification_reads r ON r.notification_id = n.id AND r.reader = ?
+      WHERE n.scope = ? AND n.read_at IS NULL AND n.severity = 'problem' AND r.read_at IS NULL`).get(reader, scope).n;
+  }
   return getDb().prepare("SELECT COUNT(*) AS n FROM notifications WHERE scope = ? AND read_at IS NULL AND severity = 'problem'").get(scope).n;
 }
 
@@ -94,13 +104,24 @@ export function latestNotificationId() {
 }
 
 /** Mark one row read (or unread with `read:false`). @returns {boolean} whether a row changed */
-export function markRead(id, { read = true, now = new Date() } = {}) {
+export function markRead(id, { read = true, now = new Date(), reader = null } = {}) {
+  if (reader) {
+    const exists = getDb().prepare('SELECT 1 FROM notifications WHERE id = ?').get(Number(id));
+    if (!exists) return false;
+    if (read) getDb().prepare('INSERT OR REPLACE INTO notification_reads (notification_id, reader, read_at) VALUES (?, ?, ?)').run(Number(id), reader, now.toISOString());
+    else getDb().prepare('DELETE FROM notification_reads WHERE notification_id = ? AND reader = ?').run(Number(id), reader);
+    return true;
+  }
   const info = getDb().prepare('UPDATE notifications SET read_at = ? WHERE id = ?').run(read ? now.toISOString() : null, Number(id));
   return info.changes > 0;
 }
 
 /** Mark every unread row of a scope read. @returns {number} rows changed */
-export function markAllRead(scope = 'schedule', { now = new Date() } = {}) {
+export function markAllRead(scope = 'schedule', { now = new Date(), reader = null } = {}) {
+  if (reader) {
+    return getDb().prepare(`INSERT OR IGNORE INTO notification_reads (notification_id, reader, read_at)
+      SELECT id, ?, ? FROM notifications WHERE scope = ? AND read_at IS NULL`).run(reader, now.toISOString(), scope).changes;
+  }
   return getDb().prepare('UPDATE notifications SET read_at = ? WHERE scope = ? AND read_at IS NULL').run(now.toISOString(), scope).changes;
 }
 
@@ -124,5 +145,6 @@ export function resolveNotifications({ ticketId = null, scheduleId = null, kinds
 /** Drop rows older than the retention window. @returns {number} rows removed */
 export function purgeNotifications({ days = NOTIFICATION_RETENTION_DAYS, now = new Date() } = {}) {
   const cutoff = new Date(now.getTime() - days * 86400000).toISOString();
+  try { getDb().prepare('DELETE FROM notification_reads WHERE notification_id IN (SELECT id FROM notifications WHERE created_at < ?)').run(cutoff); } catch { /* a hand-seeded schema without the table */ }
   return getDb().prepare('DELETE FROM notifications WHERE created_at < ?').run(cutoff).changes;
 }

package/src/core/orchestrator.mjs

@@ -50,6 +50,7 @@ import { readAskFile } from './protocol.mjs';
 import { prepareFormAsk, formAnswerValidator, downgradeQuestion } from './ask-forms.mjs';
 import { classifyError } from './recoverable-error.mjs';
 import { resolveFailure, markTerminal, isTerminal } from './failure-policy.mjs';
+import { byActor } from './identity.mjs';
 
 /** Max ask-then-resume question rounds per execution (mirrors v1's constant). */
 const MAX_QUESTION_ROUNDS = 3;
@@ -1178,6 +1179,9 @@ export class GraphOrchestrator extends RunHarness {
       runners: this._runners,             // P3's injection seam (runExecution reads ctx.runners)
       resumeSessionId: this._takeResumeSession(executionId),
       ask: (q) => this._enqueueAsk(() => this._ask(q)),
+      // Who answered question `id` (identity.mjs actor; answer() records it) — the clarifier
+      // stores it with the answer and audits it.
+      answeredBy: (id) => this.answeredBy(id),
       onEvent: (e) => this._onAgentEvent(nc.key || node.kind, e, attr),
       claudeOpts: {
         bin: this.claude.bin,
@@ -1610,11 +1614,12 @@ export class GraphOrchestrator extends RunHarness {
         }));
         this._checkAbort();
         const values = (answered && typeof answered === 'object' && answered.values) || {};
+        const formBy = this.answeredBy(`questions-${stepKey}-r${round}`);
         await writeStepQuestions(this.pipeline.id, stepKey, round, {
           agentKey: nc.key, nodeId: ctx.nodeId,
-          answers: { kind: 'form', form: formAsk.form, version: formAsk.version, values },
+          answers: { kind: 'form', form: formAsk.form, version: formAsk.version, values, ...(formBy ? { answeredBy: formBy } : {}) },
         });
-        await appendAudit(this.pipeline.dir, `${agentLabel}: form "${formAsk.form}" answered (round ${round}).`).catch(() => {});
+        await appendAudit(this.pipeline.dir, `${agentLabel}: form "${formAsk.form}" answered${byActor(formBy)} (round ${round}).`, { actor: formBy }).catch(() => {});
         await rm(qPath, { force: true }).catch(() => {});
         const step = this.state.steps.find((s) => s.key === stepKey);
         if (step?.sessionId) ctx.resumeSessionId = step.sessionId;
@@ -1643,10 +1648,11 @@ export class GraphOrchestrator extends RunHarness {
       const answers = normalizeClarifyAnswer(payload, questions);
       const byId = new Map(questions.map((q) => [q.id, q]));
       const enriched = answers.map((a) => ({ id: a.id, question: byId.get(a.id)?.question || '', choice: a.choice }));
+      const answerBy = this.answeredBy(`questions-${stepKey}-r${round}`);
       await writeStepQuestions(this.pipeline.id, stepKey, round, {
-        agentKey: nc.key, nodeId: ctx.nodeId, answers: { answers: enriched },
+        agentKey: nc.key, nodeId: ctx.nodeId, answers: { answers: enriched, ...(answerBy ? { answeredBy: answerBy } : {}) },
       });
-      await appendAudit(this.pipeline.dir, `${agentLabel}: ${enriched.length} answer(s) received (round ${round}).`).catch(() => {});
+      await appendAudit(this.pipeline.dir, `${agentLabel}: ${enriched.length} answer(s) received${byActor(answerBy)} (round ${round}).`, { actor: answerBy }).catch(() => {});
       // Consume the processed round file: the DB row is authoritative, and a
       // surviving file would re-gate the user on a crash/pause-resumed re-run.
       await rm(qPath, { force: true }).catch(() => {});

package/src/core/phases.mjs

@@ -625,6 +625,8 @@ export function runOpts(ctx, { role, prompt, systemPrompt, allowedTools }) {
     permissionRules: c.permissionRules,
     envScrub: c.envScrub,
     envAllowlist: c.envAllowlist,
+    // Every role and node is a pipeline agent: under WORCA_AGENT_USER when the container has one.
+    asAgent: true,
     bin: c.bin,
     mock: c.mock,
     signal: ctx.signal,

package/src/core/pipeline-delete.mjs

@@ -31,6 +31,7 @@ import {
 import { branchExists, hasGh, findPrForBranch } from './git-info.mjs';
 import { retainedWorkPatchName } from './results.mjs';
 import { deleteCommentsForRun } from './diff-comments.mjs';
+import { byActor } from './identity.mjs';
 
 // Statuses for which deletion is refused (the entry is or may be live).
 const ACTIVE = new Set(['running', 'starting', 'created', 'pausing']);
@@ -275,7 +276,7 @@ export async function archivePipeline({ projectDir = null, key = null, workspace
  * preserving the pipeline row and artifact directory. Every live checkout is
  * snapshotted first; any snapshot failure aborts before removal.
  */
-export async function discardRetainedWorktrees({ projectDir = null, key = null, workspaceKey = null, id } = {}) {
+export async function discardRetainedWorktrees({ projectDir = null, key = null, workspaceKey = null, id, by = null } = {}) {
   if (!id || typeof id !== 'string') throw err('id is required', 'BAD_REQUEST');
   const storeKey = workspaceKey
     ? `workspaces/${workspaceKey}`
@@ -427,8 +428,8 @@ export async function discardRetainedWorktrees({ projectDir = null, key = null,
     else report.warnings.push(`run-root: ${removal.reason || 'removal refused'}`);
   }
   await appendAudit(runDir,
-    `Discarded ${report.worktrees.length} retained worktree(s) after saving recovery patch(es): ` +
-    patches.map((p) => `\`${p}\``).join(', ')).catch(() => {});
+    `Discarded ${report.worktrees.length} retained worktree(s)${byActor(by)} after saving recovery patch(es): ` +
+    patches.map((p) => `\`${p}\``).join(', '), { actor: by }).catch(() => {});
   return report;
 }
 

package/src/core/plugin-repo.mjs

@@ -16,16 +16,20 @@ import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { pluginsRoot, pluginDir, readPluginsLock } from './plugins-lock.mjs';
 import { normalizeManifest, findEscapingSymlinks } from './plugin-manifest.mjs';
+import { githubEnv } from './github-credentials.mjs';
 
 const execFileP = promisify(execFile);
-const defaultExec = (cmd, args, opts = {}) =>
-  execFileP(cmd, args, {
+const defaultExec = async (cmd, args, opts = {}) => {
+  // The read credential for this call (a fresh App token in App mode); a failed mint leaves none.
+  const { env } = await githubEnv('read');
+  return execFileP(cmd, args, {
     maxBuffer: 16 * 1024 * 1024,
     timeout: 120_000,
     killSignal: 'SIGKILL',
-    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    env: { ...env, GIT_TERMINAL_PROMPT: '0' },
     ...opts,
   });
+};
 
 /** Filesystem slug for a repo URL — shared by the bare-cache dir and marketplace
  *  ids. Injective: a readable prefix plus an 8-hex digest of the EXACT input, so

package/src/core/policy/gate.mjs

@@ -38,13 +38,15 @@ export async function teamCapsForTarget({ projectDir = null, workspaceId = null
 }
 
 const usd = (n) => Number(n).toFixed(2);
+/** A person (identity.mjs actor) worth recording: not empty, not 'local'. */
+const personOf = (by) => (typeof by === 'string' && by.trim() && by !== 'local' ? by.trim() : null);
 
 /**
  * The team TOTAL cap at a run entry. `pastTeamCap` records the once-per-window acknowledgement
  * (design §7) and lets the run through; a cap with `requireReason` refuses an empty reason.
  * @returns {Promise<{blocked:false, caps:object, ack?:object} | {blocked:true, caps:object, error:string, code:'team_total'|'reason_required', policy:object}>}
  */
-export async function checkTeamTotalGate(target, { pastTeamCap = false, reason = null, unattended = false, now = new Date() } = {}) {
+export async function checkTeamTotalGate(target, { pastTeamCap = false, reason = null, unattended = false, now = new Date(), by = null } = {}) {
   const caps = await teamCapsForTarget(target);
   const { total, policy, period } = caps;
   if (!policy || total.binding !== 'team' || total.cap == null) return { blocked: false, caps };
@@ -60,7 +62,7 @@ export async function checkTeamTotalGate(target, { pastTeamCap = false, reason =
   if (pastTeamCap) {
     const clean = cleanReason(reason);
     if (team.requireReason && !clean) return { blocked: true, caps, code: 'reason_required', error: `the team policy on ${policy.home} requires a reason to continue past its total cap`, policy: detail };
-    const ack = setTotalAck(ackKey, policy.home, windowStartMs, { reason: clean });
+    const ack = setTotalAck(ackKey, policy.home, windowStartMs, { reason: clean, ...(personOf(by) ? { by: personOf(by) } : {}) });
     return { blocked: false, caps, ack };
   }
   return { blocked: true, caps, code: 'team_total', error: `team total cap reached ($${usd(spent)} >= $${usd(total.cap)} this ${w}, ${policy.home})`, policy: detail };
@@ -71,7 +73,7 @@ export async function checkTeamTotalGate(target, { pastTeamCap = false, reason =
  * the run, design §7) and lets the resume through.
  * @returns {{blocked:false} | {blocked:true, error:string, code:'team_pipeline'|'reason_required', policy:object}}
  */
-export function checkTeamPipelineGate(caps, { pipelineId, spentSoFar = 0, pastTeamCap = false, reason = null, unattended = false } = {}) {
+export function checkTeamPipelineGate(caps, { pipelineId, spentSoFar = 0, pastTeamCap = false, reason = null, unattended = false, by = null } = {}) {
   const { pipeline, policy } = caps;
   // The team SOFT cap is checked whether or not it is the tighter number (the local override
   // never bypasses it — run-harness._checkCostLimits applies the same rule at every boundary).
@@ -84,8 +86,10 @@ export function checkTeamPipelineGate(caps, { pipelineId, spentSoFar = 0, pastTe
   if (pastTeamCap) {
     const clean = cleanReason(reason);
     if (team.requireReason && !clean) return { blocked: true, code: 'reason_required', error: `the team policy on ${policy.home} requires a reason to continue past its cost cap`, policy: detail };
-    writePolicyState(pipelineId, { home: policy.home, sha: policy.sha, overrides: ['pipeline'], ...(clean ? { reason: clean } : {}) });
-    return { blocked: false, overridden: true };
+    // Who chose to continue, next to why (identity.mjs); absent for 'local' / unknown.
+    writePolicyState(pipelineId, { home: policy.home, sha: policy.sha, overrides: ['pipeline'], ...(clean ? { reason: clean } : {}), ...(personOf(by) ? { overriddenBy: personOf(by) } : {}) });
+    // `fresh`: this request armed the override (the caller audits who and why).
+    return { blocked: false, overridden: true, fresh: true, reason: clean || null };
   }
   return { blocked: true, code: 'team_pipeline', error: `team cost cap reached ($${usd(spentSoFar)} >= $${usd(team.value)}, ${policy.home})`, policy: detail };
 }

package/src/core/policy/state.mjs

@@ -66,14 +66,14 @@ export function readTotalAck(projectKey, home, windowStartMs) {
 }
 
 /** Record the acknowledgement; older windows are swept so the blob never grows. */
-export function setTotalAck(projectKey, home, windowStartMs, { reason = null } = {}) {
+export function setTotalAck(projectKey, home, windowStartMs, { reason = null, by = null } = {}) {
   const prefs = readTeamPolicyPrefs(projectKey);
   const acks = {};
   for (const [k, v] of Object.entries(prefs?.acks && typeof prefs.acks === 'object' ? prefs.acks : {})) {
     const ms = Number(k.split('|')[1]);
     if (Number.isFinite(ms) && ms >= windowStartMs) acks[k] = v;
   }
-  acks[ackKey(home, windowStartMs)] = { at: new Date().toISOString(), reason: cleanReason(reason) };
+  acks[ackKey(home, windowStartMs)] = { at: new Date().toISOString(), reason: cleanReason(reason), ...(by ? { by } : {}) };
   writeTeamPolicyPrefs(projectKey, { acks });
   return acks[ackKey(home, windowStartMs)];
 }

package/src/core/policy/sync.mjs

@@ -276,12 +276,13 @@ function sameContent(a, b) {
  * mode 'follow' → create a marker { delegateTo }; or join; with change:true rewrite an existing marker.
  * @returns {Promise<{action:'created'|'joined'|'changed', slug:string}>}
  */
-export async function enableTeamPolicy(projectDir, { mode = 'here', delegateTo = null, change = false, title = '', now = new Date() } = {}) {
+export async function enableTeamPolicy(projectDir, { mode = 'here', delegateTo = null, change = false, title = '', now = new Date(), by = null } = {}) {
   if (mode !== 'here' && mode !== 'follow') throw policyError('BAD_REQUEST', 'mode must be "here" or "follow"');
   const { slug, hasOrigin } = await projectSlug(projectDir);
   if (!hasOrigin) throw policyError('NO_ORIGIN', 'this project has no origin remote — a team policy lives on origin, so there is nowhere to put it');
   const target = mode === 'follow' ? (await validateFollowTarget(delegateTo, slug)).slug : null;
-  const user = await gitUserName(projectDir);
+  // The person who asked (identity.mjs) when known; else, as before, the checkout's git user.
+  const user = (typeof by === 'string' && by.trim() && by !== 'local' ? by.trim() : null) ?? await gitUserName(projectDir);
   const doc = mode === 'follow'
     ? { schema: POLICY_SCHEMA, enabledAt: stampNow(now), enabledBy: user, delegateTo: target }
     : emptyPolicyDoc({ updatedBy: user, title: title || `${slug} team policy`, now });
@@ -337,7 +338,7 @@ async function rewriteMarker(slug, projectDir, doc) {
  * is a caller bug and answers BAD_REQUEST with the list. A rejection is thrown VERBATIM.
  * @returns {Promise<{ok:true, slug:string, sha:string|null, doc:object}>}
  */
-export async function publishPolicy(projectDir, rawDoc, { message = null, now = new Date() } = {}) {
+export async function publishPolicy(projectDir, rawDoc, { message = null, now = new Date(), by = null } = {}) {
   const prefs = (await discoverPolicy(projectDir, { force: true }).catch(() => null)) || readTeamPolicyPrefs(projectKey(projectDir)) || {};
   if (!prefs.present) throw policyError('NOT_HOME', `this project has no ${POLICY_BRANCH} branch`);
   if (!prefs.docKnown) throw policyError('FETCH_FAILED', `could not read the ${POLICY_BRANCH} branch; try again`);
@@ -347,7 +348,7 @@ export async function publishPolicy(projectDir, rawDoc, { message = null, now =
   if (warnings.length) throw policyError('BAD_REQUEST', `the document has ${warnings.length} problem(s): ${warnings[0]}`, { warnings });
   const slug = prefs.slug;
   doc.updatedAt = stampNow(now);
-  doc.updatedBy = await gitUserName(projectDir);
+  doc.updatedBy = (typeof by === 'string' && by.trim() && by !== 'local' ? by.trim() : null) ?? await gitUserName(projectDir);
   delete doc.delegateTo;
   const body = serializePolicyDoc(doc);
   const commitMsg = message && String(message).trim() ? `policy: ${String(message).trim().slice(0, 120)}` : 'policy: update team policy';

package/src/core/remote-access.mjs

@@ -0,0 +1,138 @@
+// Remote access behind an identity proxy (docs/remote-access.md).
+//
+// Worca is a single-user localhost tool (ui/server.mjs, S1): it accepts only
+// requests whose Host (and browser Origin) is a loopback name. Behind a proxy
+// the browser sends the public hostname, so a hosted deployment opts in with:
+//
+//   WORCA_ALLOWED_HOSTS             hostnames accepted besides loopback, comma-
+//                                   separated; ".example.com" matches subdomains
+//   WORCA_CF_ACCESS_TEAM_DOMAIN     + WORCA_CF_ACCESS_AUD: every request must carry
+//                                   a valid Cloudflare Access token for that app
+//   WORCA_INSECURE_NO_IDENTITY_CHECK=1  run with an allowlist but no token check
+//                                   (the proxy alone is trusted); never the default
+//
+// Fail closed: an allowlist without an identity check is a startup error unless
+// the insecure flag says so explicitly. With none of these set, nothing changes.
+import { createAccessVerifier, normalizeTeamDomain } from './cf-access.mjs';
+
+export const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+const LOOPBACK_ADDRS = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+const LOOPBACK_BINDS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+const HOST_ENTRY_RE = /^\.?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
+
+/** Hostname (no port) from a Host header value or full Origin URL, or null. */
+export function hostnameOf(value) {
+  if (!value) return null;
+  try {
+    return new URL(value.includes('://') ? value : `http://${value}`).hostname;
+  } catch {
+    return null;
+  }
+}
+
+/** "a.example.com, .example.org" -> { hosts: [...], invalid: [...] } (lowercased, deduped). */
+export function parseAllowedHosts(value) {
+  const hosts = [];
+  const invalid = [];
+  for (const raw of String(value || '').split(',')) {
+    const h = raw.trim().toLowerCase();
+    if (!h) continue;
+    if (!HOST_ENTRY_RE.test(h) || h === '.') invalid.push(raw.trim());
+    else if (!hosts.includes(h)) hosts.push(h);
+  }
+  return { hosts, invalid };
+}
+
+const truthy = (v) => /^(1|true|yes|on)$/i.test(String(v || '').trim());
+
+/** The remote-access settings from the environment. Pure: reads only `env`. */
+export function readRemoteAccessConfig(env = process.env) {
+  const { hosts, invalid } = parseAllowedHosts(env.WORCA_ALLOWED_HOSTS);
+  const teamDomain = normalizeTeamDomain(env.WORCA_CF_ACCESS_TEAM_DOMAIN);
+  const aud = String(env.WORCA_CF_ACCESS_AUD || '').trim();
+  return {
+    allowedHosts: hosts,
+    invalidHosts: invalid,
+    identity: teamDomain || aud ? { provider: 'cloudflare-access', teamDomain, aud } : null,
+    insecureNoIdentity: truthy(env.WORCA_INSECURE_NO_IDENTITY_CHECK),
+  };
+}
+
+/** True when the server answers to any non-loopback hostname. */
+export function isRemoteMode(cfg) {
+  return cfg.allowedHosts.some((h) => !LOCAL_HOSTNAMES.has(h));
+}
+
+/**
+ * Validate a config against the bind address. Errors stop the server from
+ * starting; warnings are logged. Both are one-line, actionable messages.
+ */
+export function checkRemoteAccessConfig(cfg, { bindHost = '127.0.0.1' } = {}) {
+  const errors = [];
+  const warnings = [];
+  if (cfg.invalidHosts.length) {
+    errors.push(`WORCA_ALLOWED_HOSTS has invalid entries: ${cfg.invalidHosts.join(', ')} (use hostnames like worca-01.example.com or .example.com, no scheme or port)`);
+  }
+  if (cfg.identity) {
+    if (!cfg.identity.teamDomain) errors.push('WORCA_CF_ACCESS_AUD is set but WORCA_CF_ACCESS_TEAM_DOMAIN is not');
+    if (!cfg.identity.aud) errors.push('WORCA_CF_ACCESS_TEAM_DOMAIN is set but WORCA_CF_ACCESS_AUD is not');
+  }
+  const remote = isRemoteMode(cfg);
+  if (remote && !cfg.identity && !cfg.insecureNoIdentity) {
+    errors.push('WORCA_ALLOWED_HOSTS is set but no identity check is configured: set WORCA_CF_ACCESS_TEAM_DOMAIN and WORCA_CF_ACCESS_AUD, or set WORCA_INSECURE_NO_IDENTITY_CHECK=1 if a proxy you trust is the only way in');
+  }
+  if (remote && !cfg.identity && cfg.insecureNoIdentity) {
+    warnings.push('WORCA_INSECURE_NO_IDENTITY_CHECK=1: worca checks no identity; anyone who reaches it controls this machine');
+  }
+  if (cfg.identity && cfg.insecureNoIdentity) {
+    warnings.push('WORCA_INSECURE_NO_IDENTITY_CHECK is ignored: a Cloudflare Access check is configured and enforced');
+  }
+  if (cfg.identity && !remote) {
+    warnings.push('WORCA_CF_ACCESS_* is set but WORCA_ALLOWED_HOSTS is empty: only localhost requests are accepted');
+  }
+  if (!LOOPBACK_BINDS.has(String(bindHost).toLowerCase()) && !remote) {
+    warnings.push(`listening on ${bindHost} but WORCA_ALLOWED_HOSTS is empty: every request not addressed to localhost gets a 403`);
+  }
+  return { errors, warnings };
+}
+
+/** (req) => true when Host and (if present) Origin are loopback or allowlisted. */
+export function createHostGuard(allowedHosts = []) {
+  const allowed = (name) => {
+    if (!name) return false;
+    const h = name.toLowerCase();
+    if (LOCAL_HOSTNAMES.has(h)) return true;
+    return allowedHosts.some((a) => (a.startsWith('.') ? h.endsWith(a) : h === a));
+  };
+  return function isAllowedRequest(req) {
+    if (!allowed(hostnameOf(req.headers.host))) return false;
+    const origin = req.headers.origin;
+    if (origin && !allowed(hostnameOf(origin))) return false;
+    return true;
+  };
+}
+
+/**
+ * A connection from inside this machine/container (`worca ui stop`, the CLI,
+ * curl in a shell): loopback TCP peer AND loopback Host. A proxy on another
+ * host (cloudflared as its own service) never matches, so it is always checked.
+ */
+export function isInContainer(req) {
+  return LOOPBACK_ADDRS.has(req.socket?.remoteAddress)
+    && LOCAL_HOSTNAMES.has(hostnameOf(req.headers.host));
+}
+
+/**
+ * The identity check for this config, or null when none applies (local mode,
+ * or the explicit insecure flag). Provider-agnostic: returns
+ * `(req) => Promise<{ email, sub } | null>`; rejects only when the provider
+ * cannot be reached (the caller answers 503).
+ */
+export function createIdentityCheck(cfg, { fetchImpl, now } = {}) {
+  if (!cfg.identity) return null;
+  if (cfg.identity.provider === 'cloudflare-access') {
+    const verify = createAccessVerifier({ teamDomain: cfg.identity.teamDomain, aud: cfg.identity.aud, fetchImpl, now });
+    return (req) => verify(req.headers['cf-access-jwt-assertion']);
+  }
+  throw new Error(`unknown identity provider: ${cfg.identity.provider}`);
+}