@worca/app 1.4.0 → 1.5.0-rc.2

package/src/cli/schedule.mjs

@@ -242,6 +242,16 @@ async function serverIsUp() {
  * `worca … --at/--every/--cron`: write the ticket or the schedule. Returns
  * { ticket, schedule, spec } — the caller decides whether to --wait.
  */
+// Schedule attribution (identity.mjs): the CLI is the machine itself, so it records 'local'.
+const CLI_ACTOR = 'local';
+/** A stored actor worth naming: a person, never 'local' or empty. */
+const person = (v) => (typeof v === 'string' && v && v !== 'local' ? v : null);
+/** The list's "by" column: only for rows a person created or changed. */
+function byCol(x) {
+  const who = person(x.updatedBy) || person(x.createdBy);
+  return who ? `  ·  by ${who}` : '';
+}
+
 export async function createFromFlags(flags, { projectDir, extras, promptText, spec, out, c }) {
   const title = fallbackTitle(flags, promptText);
   let ticket, schedule = null;
@@ -250,7 +260,7 @@ export async function createFromFlags(flags, { projectDir, extras, promptText, s
     const request = await requestFromFlags(flags, { projectDir, extras, promptText, stageId: id });
     ({ schedule, ticket } = createSchedule({
       id, title, projectDir, request, rule: spec.rule, overlap: spec.overlap, maxFailures: spec.maxFailures,
-      ifMissed: spec.ifMissed, graceMin: spec.graceMin,
+      ifMissed: spec.ifMissed, graceMin: spec.graceMin, createdBy: CLI_ACTOR,
     }));
     out(`${c('green', 'Scheduled')} ${c('bold', schedule.id)} — ${describeRule(schedule.rule)} (${spec.tz})`);
     if (ticket) out(`  Next run: ${formatInstant(Date.parse(ticket.runAt), spec.tz, { withYear: true })} (in ${formatCountdown(Date.parse(ticket.runAt) - Date.now())})`);
@@ -258,11 +268,11 @@ export async function createFromFlags(flags, { projectDir, extras, promptText, s
     const id = randomUUID();
     const request = await requestFromFlags(flags, { projectDir, extras, promptText, stageId: id });
     if (spec.after) {
-      ticket = createTicket({ id, title, projectDir, request, after: { kind: spec.after.kind, id: spec.after.id }, afterPolicy: spec.afterPolicy, sourceFromPrevious: spec.sourceFromPrevious, ifMissed: spec.ifMissed, graceMin: spec.graceMin });
+      ticket = createTicket({ id, title, projectDir, request, after: { kind: spec.after.kind, id: spec.after.id }, afterPolicy: spec.afterPolicy, sourceFromPrevious: spec.sourceFromPrevious, ifMissed: spec.ifMissed, graceMin: spec.graceMin, createdBy: CLI_ACTOR });
       out(`${c('green', 'Scheduled')} ${c('bold', ticket.id.slice(0, 8))} after ‘${spec.after.title || spec.after.id.slice(0, 8)}’ (${spec.after.status})`);
     } else {
       ticket = createTicket({
-        id, title, projectDir, runAtMs: spec.runAtMs, request, ifMissed: spec.ifMissed, graceMin: spec.graceMin,
+        id, title, projectDir, runAtMs: spec.runAtMs, request, ifMissed: spec.ifMissed, graceMin: spec.graceMin, createdBy: CLI_ACTOR,
         ...(flags.wait ? { ownerPid: process.pid, ownerHost: hostname() } : {}),
       });
       out(`${c('green', 'Scheduled')} ${c('bold', ticket.id.slice(0, 8))} for ${formatInstant(spec.runAtMs, spec.tz, { withYear: true })} (in ${formatCountdown(spec.runAtMs - Date.now())})`);
@@ -381,7 +391,7 @@ export async function cmdSchedule(argv, { out, c, fail }) {
       out(c('bold', 'Repeating'));
       for (const s of series) {
         const state = s.status === 'active' ? `next ${when(s.nextRunAt)}` : s.status === 'paused' ? c('yellow', s.pauseReason === 'failure_streak' ? `paused after ${s.failureStreak} failures` : 'paused') : 'ended';
-        out(`  ${s.id}  ${s.sentence}  ·  ${state}  ·  ${where(s)}  ·  ${s.title || ''}`);
+        out(`  ${s.id}  ${s.sentence}  ·  ${state}  ·  ${where(s)}  ·  ${s.title || ''}${byCol(s)}`);
       }
     }
     if (tickets.length) {
@@ -389,7 +399,7 @@ export async function cmdSchedule(argv, { out, c, fail }) {
       for (const t of tickets) {
         const st = t.after && t.status === 'scheduled' ? 'waiting' : t.status === 'scheduled' ? `in ${formatCountdown(Date.parse(t.runAt) - Date.now()) || 'a moment'}` : t.status === 'missed' ? c('yellow', 'missed') : t.status;
         const held = t.ownerPid != null && t.status === 'scheduled' ? '  ·  held by a waiting terminal' : '';
-        out(`  ${t.id.slice(0, 8)}  ${t.after ? `after ${afterLabel(t, { withStatus: false })}` : when(t.runAt)}  ·  ${st}  ·  ${where(t)}  ·  ${t.title || ''}${held}`);
+        out(`  ${t.id.slice(0, 8)}  ${t.after ? `after ${afterLabel(t, { withStatus: false })}` : when(t.runAt)}  ·  ${st}  ·  ${where(t)}  ·  ${t.title || ''}${byCol(t)}${held}`);
       }
     }
     const unread = unreadCount('schedule');
@@ -421,6 +431,8 @@ export async function cmdSchedule(argv, { out, c, fail }) {
     out(c('bold', item.title || label));
     out(`  id         ${item.id}`);
     out(`  target     ${where(item)}`);
+    if (person(item.createdBy)) out(`  created by ${person(item.createdBy)}`);
+    if (person(item.updatedBy) && item.updatedBy !== item.createdBy) out(`  changed by ${person(item.updatedBy)}`);
     if (kind === 'recurring') {
       out(`  repeats    ${item.sentence} (${item.tz})`);
       out(`  status     ${item.status}${item.pauseReason ? ` (${item.pauseReason.replace(/_/g, ' ')})` : ''}`);
@@ -446,7 +458,7 @@ export async function cmdSchedule(argv, { out, c, fail }) {
       const p = predecessorState(item.after, { policy: item.after.policy });
       if (!p.pipelineId || !previousBranchesOf(p.pipelineId)) fail(`Start ‘${p.title || 'the run before it'}’ first, or change its source branch`);
     }
-    const t = kind === 'recurring' ? runScheduleNow(item.id) : requestRunNow(item.id);
+    const t = kind === 'recurring' ? runScheduleNow(item.id, { by: CLI_ACTOR }) : requestRunNow(item.id, { by: CLI_ACTOR });
     if (!t) fail(`${label} is ${item.status} and cannot be started`);
     out(`Asked ${c('bold', label)} to start now.`);
     if (!(await serverIsUp()) && t.ownerPid == null) out(c('yellow', 'Note: no Worca server is up — it starts as soon as `worca ui` runs.'));
@@ -455,7 +467,7 @@ export async function cmdSchedule(argv, { out, c, fail }) {
   if (verb === 'cancel') {
     if (kind === 'recurring') { deleteSchedule(item.id); out(`Deleted the repeating schedule ${c('bold', label)}.`); return 0; }
     if (item.scheduleId) fail(`${label} is the next run of ${item.scheduleId} — use: worca schedule skip ${item.scheduleId}`);
-    if (!cancelTicket(item.id)) fail(`${label} is ${item.status} and can no longer be canceled`);
+    if (!cancelTicket(item.id, { by: CLI_ACTOR })) fail(`${label} is ${item.status} and can no longer be canceled`);
     out(`Canceled ${c('bold', label)}.`);
     return 0;
   }
@@ -474,7 +486,7 @@ export async function cmdSchedule(argv, { out, c, fail }) {
       const policy = rest.includes('--after-any') ? 'any' : (item.after ? item.after.policy : 'done');
       const r = resolveAfterRef({ kind: ref.kind, id: ref.id }, { projectDir: item.projectDir, workspaceId: item.workspaceId, policy, selfId: item.id });
       if (!r.ok) fail(r.error);
-      if (!updateTicket(item.id, { after: { kind: r.after.kind, id: r.after.id }, afterPolicy: policy, ...(rest.includes('--source-from-previous') ? { sourceFromPrevious: true } : {}) })) fail(`${label} is ${item.status} and can no longer be moved`);
+      if (!updateTicket(item.id, { after: { kind: r.after.kind, id: r.after.id }, afterPolicy: policy, ...(rest.includes('--source-from-previous') ? { sourceFromPrevious: true } : {}) }, { by: CLI_ACTOR })) fail(`${label} is ${item.status} and can no longer be moved`);
       out(`Moved ${c('bold', label)} after ‘${r.after.title || r.after.id.slice(0, 8)}’.`);
       return 0;
     }
@@ -482,12 +494,13 @@ export async function cmdSchedule(argv, { out, c, fail }) {
     const at = parseAt(value, { nowMs: Date.now(), tz });
     if (!at.ok) fail(at.error);
     if (at.ms <= Date.now()) fail('--at: that time is in the past');
-    if (!updateTicket(item.id, { runAtMs: at.ms })) fail(`${label} is ${item.status} and can no longer be moved`);
+    if (!updateTicket(item.id, { runAtMs: at.ms }, { by: CLI_ACTOR })) fail(`${label} is ${item.status} and can no longer be moved`);
     out(`Moved ${c('bold', label)} to ${formatInstant(at.ms, tz, { withYear: true })} (in ${formatCountdown(at.ms - Date.now())}).`);
     return 0;
   }
   if (kind !== 'recurring') fail(`${verb} applies to a repeating schedule; ${label} runs once`);
-  const s = verb === 'skip' ? skipNext(item.id) : verb === 'pause' ? pauseSchedule(item.id) : resumeSchedule(item.id);
+  const opt = { by: CLI_ACTOR };
+  const s = verb === 'skip' ? skipNext(item.id, opt) : verb === 'pause' ? pauseSchedule(item.id, opt) : resumeSchedule(item.id, opt);
   if (!s) fail(`${label} is ${item.status}`);
   out(verb === 'skip' ? `Skipped. Next run: ${when(s.nextRunAt)}.` : verb === 'pause' ? `Paused ${c('bold', label)}.` : `Resumed ${c('bold', label)}. Next run: ${when(s.nextRunAt)}.`);
   return 0;

package/src/cli/worca-cc.mjs

@@ -39,6 +39,7 @@ import { pauseExitCode, describePauseReason, promptOptions, REASON } from '../co
 import { effectiveDebugSpawn } from '../core/settings.mjs';
 import { SCHEDULE_VALUE_FLAGS, wantsSchedule, readScheduleFlags, createFromFlags, waitAndRun, cmdSchedule } from './schedule.mjs';
 import { cmdModels } from './models.mjs';
+import { cmdContainer } from './container.mjs';
 import {
   DEFAULT_UI_HOST, DEFAULT_UI_PORT, probeUi, stopUi, readUiInstance, uiUrl, waitForUiState,
 } from '../core/ui-instance.mjs';
@@ -251,6 +252,8 @@ Usage:
 
 Subcommands:
   add [name] [--path <dir>]   Register a project. Defaults: name = basename(path), path = cwd.
+  add --clone <https-url> [--branch <b>] [--name <folder>]
+                              Clone a repository into the projects folder and register it.
   list                        List registered projects (tab-separated; missing dirs are flagged).
   remove <name>               Remove a registered project by name (case-insensitive).
   resume <pipelineId>         Continue a paused pipeline (re-attaches Claude sessions).
@@ -266,11 +269,14 @@ Subcommands:
                               Run the web UI (default http://localhost:4317). See: worca ui help
   workflow <cmd> [...]        Export a workflow (Claude Code skill, JSON, or plugin) / import JSON: list|export|import. See: worca workflow help
   metrics push [--project <path>]   Push pending team-metrics run records (headless flush)
+  metrics pr-workflow [--project <path>]   Add the GitHub Action that records PR merges for the Timeline
   policy <cmd> [...]          Team policy from the worca-policy branch: show|pull|init|setup. See: worca policy help
   schedule <cmd> [...]        Manage scheduled runs: list|show|run-now|move|cancel|skip|pause|resume|log.
                               See: worca schedule help
   models <cmd> [...]          Model catalog + providers: list|providers|login|logout|import|test|set.
                               See: worca models help
+  container <cmd> [...]       Run Worca in a container: init|up|down|status|logs|pull|login|shell|run|where.
+                              See: worca container help (docs/docker.md)
   help                        Print this help (same as --help).
   version                     Print the version (same as --version).
 
@@ -1049,10 +1055,12 @@ function runInstall(targetDir, passthrough) {
 
 // ── project registry subcommands ──────────────────────────────────────────────
 
-/** Parse a tiny argv slice for the `add` subcommand. Supports --path/--path=<dir>. */
+/** Parse a tiny argv slice for the `add` subcommand. Supports --path/--path=<dir> and
+ *  --clone <url> [--branch <b>] [--name <folder>]. */
 function parseAddArgs(argv) {
   const positionals = [];
   let pathArg = null;
+  const clone = { url: null, branch: null, name: null };
   for (let i = 0; i < argv.length; i++) {
     let a = argv[i];
     let inline;
@@ -1065,17 +1073,44 @@ function parseAddArgs(argv) {
       const v = inline !== undefined ? inline : argv[++i];
       if (v === undefined) fail('Flag --path requires a value.');
       pathArg = v;
+    } else if (a === '--clone' || a === '--branch' || a === '--name') {
+      const v = inline !== undefined ? inline : argv[++i];
+      if (v === undefined) fail(`Flag ${a} requires a value.`);
+      clone[a === '--clone' ? 'url' : a.slice(2)] = v;
     } else if (a.startsWith('-')) {
       fail(`Unknown flag: ${a}`);
     } else {
       positionals.push(a);
     }
   }
-  return { name: positionals[0], path: pathArg };
+  if ((clone.branch || clone.name) && !clone.url) fail('--branch and --name go with --clone.');
+  if (clone.url && pathArg) fail('--clone and --path cannot be combined: the clone goes into the projects folder.');
+  return { name: positionals[0], path: pathArg, clone: clone.url ? clone : null };
+}
+
+/** `worca add --clone`: the same path as the UI's Clone from URL (src/core/clone-project.mjs). */
+async function cmdAddClone(clone, positionalName) {
+  const { cloneProject } = await import('../core/clone-project.mjs');
+  const { getProjectsRoot } = await import('../core/settings.mjs');
+  try {
+    out(`Cloning ${clone.url} …`);
+    const { project } = await cloneProject({ url: clone.url, branch: clone.branch, name: clone.name || positionalName || null },
+      { projectsRoot: getProjectsRoot(), listProjects, addProject });
+    out(`Added project "${project.name}" -> ${project.path}`);
+    try {
+      const m = await import('../core/metrics/sync.mjs');
+      await m.discoverProject(project.path, { force: true });
+    } catch { /* metrics never block `worca add` */ }
+    return 0;
+  } catch (err) {
+    process.stderr.write(`worca: ${err?.message || err}${err?.code ? ` (${err.code})` : ''}\n`);
+    return 1;
+  }
 }
 
 async function cmdAdd(argv) {
-  const { name: rawName, path: rawPath } = parseAddArgs(argv);
+  const { name: rawName, path: rawPath, clone } = parseAddArgs(argv);
+  if (clone) return cmdAddClone(clone, rawName);
   // Always route through normalizeProjectPath so display, storage, and
   // basename() all see exactly the same string addProject will persist.
   const target = normalizeProjectPath(rawPath) || resolve(process.cwd());
@@ -2879,6 +2914,12 @@ const METRICS_HELP = `worca metrics — team metrics (git-backed, team-wide run
 Usage:
   worca metrics push [--project <path>]   Flush pending run records to their worca-metrics branch.
                                           Without --project, every outbox on this machine is flushed.
+  worca metrics pr-workflow [--project <path>] [--force] [--print]
+                                          Add the GitHub Action that records pull-request events
+                                          (opened, merged, closed) on worca-metrics, so the Team
+                                          metrics Timeline knows when work shipped without gh.
+                                          Commit and push the file afterwards. --print writes it
+                                          to stdout instead.
   worca metrics help
 
 Exit codes: 0 all pushed (or nothing pending) · 1 at least one outbox could not be pushed.
@@ -2912,6 +2953,22 @@ async function cmdMetrics(argv) {
         }
         return failed ? 1 : 0;
       }
+      case 'pr-workflow': {
+        const a = pluginArgs(rest, ['--project'], ['--force', '--print']);
+        if (a._.length) fail(`unexpected argument "${a._[0]}" — see: worca metrics help`);
+        const prs = await import('../core/metrics/prs.mjs');
+        if (a.print) { process.stdout.write(await prs.prWorkflowText()); return 0; }
+        const dir = resolve(a.project || process.cwd());
+        const r = await prs.installPrWorkflow(dir, { force: !!a.force });
+        const rel = prs.PR_WORKFLOW_PATH;
+        if (r.status === 'differs') {
+          process.stderr.write(`worca metrics pr-workflow: ${rel} already exists and differs — re-run with --force to replace it\n`);
+          return 1;
+        }
+        out(r.status === 'unchanged' ? `${c('green', '✓')} ${rel} is up to date` : `${c('green', '✓')} ${r.status} ${rel}`);
+        if (r.status !== 'unchanged') out(`  Commit and push it to the default branch. Run it once from the Actions tab ("Run workflow") to backfill recent pull requests.`);
+        return 0;
+      }
       default:
         fail(`unknown metrics verb "${verb}" — see: worca metrics help`);
     }
@@ -3047,7 +3104,7 @@ async function drainMetricsFlushes() {
 
 // ── main ──────────────────────────────────────────────────────────────────────────
 
-const SUBCOMMANDS = new Set(['add', 'list', 'remove', 'resume', 'doctor', 'plugin', 'marketplace', 'config', 'ui', 'workflow', 'metrics', 'script', 'policy', 'schedule', 'models']);
+const SUBCOMMANDS = new Set(['add', 'list', 'remove', 'resume', 'doctor', 'plugin', 'marketplace', 'config', 'ui', 'workflow', 'metrics', 'script', 'policy', 'schedule', 'models', 'container']);
 
 /** Levenshtein distance, two-row. Only ever called on short argv tokens. */
 function editDistance(a, b) {
@@ -3112,6 +3169,7 @@ async function main() {
     if (sub === 'policy') return cmdPolicy(rest);
     if (sub === 'schedule') return cmdSchedule(rest, { out, c, fail });
     if (sub === 'models') return cmdModels(rest, { out, c, fail });
+    if (sub === 'container') return cmdContainer(rest, { out, c, fail });
   }
   // `worca --ui [...]` is the historical spelling of `worca ui start [...]`; hand the
   // remaining tokens to the ui parser so --port/--open/--mock work with either.

package/src/core/agent-user.mjs

@@ -0,0 +1,92 @@
+// Agents under their own uid (docker/entrypoint.sh, single-volume hosts).
+//
+// Worca never hands an agent a credential (github-credentials.mjs), but an agent
+// running as the server's own user could still read the server's environment
+// through /proc/<pid>/environ, or worca's settings and database. So on a hosted
+// container the entrypoint creates the boundary and tells the server about it:
+//
+//   WORCA_AGENT_USER   the user agents run as (worca-agent)
+//   WORCA_AGENT_HOME   that user's HOME (its own ~/.claude, npm and pip caches)
+//   WORCA_AGENT_GID    the group server and agent share (projects, runs, store)
+//
+// Each agent spawn becomes `sudo -n -E -u <user> -- <bin> …` (a sudoers rule
+// lets the server switch to that one user and nothing else). Unset = agents run
+// as the server, as on every local install.
+import { spawn, spawnSync } from 'node:child_process';
+import { chmodSync, chownSync, readdirSync, statSync } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+
+const USER_RE = /^[a-z_][a-z0-9_-]{0,31}$/;
+
+/** { user, home, gid } when agent isolation is on, else null. Pure: reads only `env`. */
+export function agentIdentity(env = process.env) {
+  const user = String(env.WORCA_AGENT_USER || '').trim();
+  const home = String(env.WORCA_AGENT_HOME || '').trim();
+  if (!USER_RE.test(user) || !isAbsolute(home)) return null;
+  const gid = Number.parseInt(env.WORCA_AGENT_GID, 10);
+  return { user, home, gid: Number.isInteger(gid) && gid > 0 ? gid : null };
+}
+
+/** An absolute path for `bin` from PATH (sudo's secure_path must not change which binary runs). */
+export function resolveOnPath(bin, pathVar = process.env.PATH || '', isFile = defaultIsFile) {
+  if (isAbsolute(bin)) return bin;
+  if (bin.includes('/')) return null;
+  for (const dir of String(pathVar).split(delimiter)) {
+    if (dir && isAbsolute(dir) && isFile(join(dir, bin))) return join(dir, bin);
+  }
+  return null;
+}
+
+function defaultIsFile(p) {
+  try { return statSync(p).isFile(); } catch { return false; }
+}
+
+/**
+ * The spawn for one agent command under `id`: `sudo -n -E -u <user> -- <abs bin> …args`,
+ * with the agent's HOME, USER and LOGNAME in its env. Throws when `bin` cannot be resolved,
+ * rather than running something else.
+ */
+export function agentSpawn(bin, args, env, id, { isFile = defaultIsFile } = {}) {
+  const abs = resolveOnPath(bin, env.PATH || process.env.PATH || '', isFile);
+  if (!abs) throw new Error(`cannot run ${bin} as ${id.user}: not found on PATH`);
+  return {
+    file: 'sudo',
+    args: ['-n', '-E', '-u', id.user, '--', abs, ...args],
+    env: { ...env, HOME: id.home, USER: id.user, LOGNAME: id.user },
+  };
+}
+
+/** SIGKILL every process of the agent's group `pgid` (the server cannot signal another uid;
+ *  sudo relays SIGTERM, but a SIGKILLed sudo would orphan its command). Best effort. */
+export function killAgentGroup(pgid, id, spawnImpl = spawn) {
+  if (!id || !Number.isInteger(pgid) || pgid <= 1) return;
+  try {
+    const c = spawnImpl('sudo', ['-n', '-u', id.user, '--', 'kill', '-KILL', '--', `-${pgid}`], { stdio: 'ignore' });
+    c.on?.('error', () => {});
+    c.unref?.();
+  } catch { /* nothing left to kill */ }
+}
+
+/** killAgentGroup, synchronously: for a process 'exit' listener, which cannot wait. */
+export function killAgentGroupSync(pgid, id, spawnSyncImpl = spawnSync) {
+  if (!id || !Number.isInteger(pgid) || pgid <= 1) return;
+  try {
+    spawnSyncImpl('sudo', ['-n', '-u', id.user, '--', 'kill', '-KILL', '--', `-${pgid}`], { stdio: 'ignore', timeout: 5000 });
+  } catch { /* nothing left to kill */ }
+}
+
+/** Let the agent read a directory the server made for one spawn (staged prompt files):
+ *  the shared group, group read/traverse. Best effort; a failure surfaces as the agent's
+ *  own read error. */
+export function shareWithAgent(dir, id) {
+  if (!id || id.gid == null) return;
+  try {
+    chownSync(dir, -1, id.gid);
+    chmodSync(dir, 0o750);
+    for (const name of readdirSync(dir)) {
+      const p = join(dir, name);
+      chownSync(p, -1, id.gid);
+      chmodSync(p, 0o640);
+    }
+  } catch { /* the agent reports what it cannot read */ }
+}

package/src/core/artifacts.mjs

@@ -21,6 +21,7 @@ import { RUN_LOG_FILE } from './run-log.mjs';
 import { readRunLedger } from './metrics/ledger.mjs';
 import { readPolicyState } from './policy/state.mjs';
 import { memoryTotals } from './memory-sync.mjs';
+import { actorLabel } from './identity.mjs';
 
 // ── DB row <-> state object mapping (Phase 3) ──────────────────────────────────
 // JSON columns are TEXT; (de)serialize at THIS boundary only. Reads are fail-safe:
@@ -269,6 +270,12 @@ function formAskOf(qWrap, aWrap) {
 
 /** The two form fields a reader row carries — `{}` for a legacy row, so no legacy
  *  payload gains a key (test/step-questions-db.test.mjs pins the exact row shape). */
+/** `{answeredBy}` when the answer row names who answered (identity.mjs actor), else {} —
+ *  additive, so a row answered before attribution keeps its exact wire shape. */
+function answeredByOf(aWrap) {
+  return aWrap && typeof aWrap.answeredBy === 'string' && aWrap.answeredBy ? { answeredBy: aWrap.answeredBy } : {};
+}
+
 function formFieldsOf(qWrap, aWrap) {
   const ask = formAskOf(qWrap, aWrap);
   return ask ? { ask, formAnswer: formAnswerOf(aWrap) } : {};
@@ -305,6 +312,7 @@ export function readStepQuestions(pipelineId) {
       // gains no key at all, so its wire shape (History, get_run_progress) stays
       // byte-identical; consumers test `row.ask`, never `'ask' in row`.
       ...formFieldsOf(qWrap, aWrap),
+      ...answeredByOf(aWrap),
     };
   });
 }
@@ -384,6 +392,7 @@ export function readPipelineExtras(pipelineId) {
     questions: Array.isArray(qWrap?.questions) ? qWrap.questions : [],
     answers: Array.isArray(aWrap?.answers) ? aWrap.answers : [],
     ...formFieldsOf(qWrap, aWrap),   // spec §9: `ask` + `formAnswer` on a form row only
+    ...answeredByOf(aWrap),
   };
   const reviews = getDb().prepare(
     'SELECT kind, cycle, verdict FROM reviews WHERE pipeline_id = ? ORDER BY kind, cycle'
@@ -933,7 +942,7 @@ export async function createPipeline(projectDir, opts = {}) {
   const {
     prompt, promptFile, extras = [], title,
     promptText: precomputedPromptText = null, sourceType = null, sourceMeta = null,
-    guardrailsId = null,
+    guardrailsId = null, startedBy = null,
     workspaceKey = null, workspaceId = null, workspaceName = null,
     workspaceDescription = '', projects = null,
   } = opts;
@@ -1030,6 +1039,8 @@ export async function createPipeline(projectDir, opts = {}) {
     // unguarded runs). Creation-immutable, like sourceType: written on INSERT,
     // never touched by updates. NULL = legacy/pre-entity or non-orchestrator row.
     guardrailsId: guardrailsId || null,
+    // Who started the run (identity.mjs): creation-immutable like guardrailsId. NULL = unknown.
+    startedBy: startedBy || null,
   };
 
   // Workspace runs carry the §5.2 superset, discriminated by target:'workspace'.
@@ -1095,15 +1106,30 @@ function firstMeaningfulLine(text) {
  * @param {string} markdownLine
  * @returns {Promise<void>}
  */
-export async function appendAudit(pipelineDir, markdownLine) {
-  const id = resolvePipelineId(pipelineDir);
+export async function appendAudit(pipelineDir, markdownLine, { actor = null } = {}) {
+  appendAuditById(resolvePipelineId(pipelineDir), markdownLine, { actor });
+}
+
+/**
+ * appendAudit by pipeline id (the server's human actions: PRs, archive, cap overrides).
+ * `actor` = who did it (identity.mjs; 'local' allowed), stored in its own column always;
+ * the line's text names the person only when they are not 'local' (byActor), so the
+ * History view and the markdown export read "Paused by ada@example.com." Best-effort.
+ */
+export function appendAuditById(id, markdownLine, { actor = null } = {}) {
   if (!id) return;
   const ts = new Date().toISOString();
   const text = String(markdownLine ?? '').trim();
+  const who = typeof actor === 'string' && actor ? actor.slice(0, 200) : null;
   try {
     tx(() => {
-      getDb().prepare('INSERT INTO pipeline_events (pipeline_id, ts, text) VALUES (?, ?, ?)')
-        .run(id, ts, text);
+      if (who) {
+        getDb().prepare('INSERT INTO pipeline_events (pipeline_id, ts, text, actor) VALUES (?, ?, ?, ?)')
+          .run(id, ts, text, who);
+      } else {
+        getDb().prepare('INSERT INTO pipeline_events (pipeline_id, ts, text) VALUES (?, ?, ?)')
+          .run(id, ts, text);
+      }
     });
   } catch { /* audit is best-effort; never break a run on a logging failure */ }
 }
@@ -1164,11 +1190,11 @@ export async function writeState(pipelineDir, stateObj) {
       INSERT INTO pipelines (id, project_key, workspace_key, target, title, base_name,
         date_prefix, status, phase, cycle, started_at, updated_at, total_cost_usd,
         total_active_ms, prompt, branch, workspace_meta, stepper, tools, resume_point,
-        source_type, source_ref, guardrails_id, outcome, human_hours)
+        source_type, source_ref, guardrails_id, outcome, human_hours, started_by)
       VALUES (@id,@project_key,@workspace_key,@target,@title,@base_name,@date_prefix,
         @status,@phase,@cycle,@started_at,@updated_at,@total_cost_usd,@total_active_ms,
         @prompt,@branch,@workspace_meta,@stepper,@tools,@resume_point,
-        @source_type,@source_ref,@guardrails_id,@outcome,@human_hours)
+        @source_type,@source_ref,@guardrails_id,@outcome,@human_hours,@started_by)
       ON CONFLICT(id) DO UPDATE SET
         status=excluded.status, phase=excluded.phase, cycle=excluded.cycle,
         updated_at=excluded.updated_at, total_cost_usd=excluded.total_cost_usd,
@@ -1552,6 +1578,7 @@ function toPipelineRow(o) {
     source_type: o.sourceType ?? 'prompt',
     source_ref: s(o.sourceMeta),
     guardrails_id: o.guardrailsId ?? null,
+    started_by: o.startedBy ?? null,
     // §5.9 outcome: the derived run-level v2 facts, so a rehydrated state matches
     // a live one. NULL for a v1 run (nothing to say), so v1 rows are unchanged.
     outcome: (o.engine === 2 || o.endReached !== undefined)
@@ -1668,6 +1695,7 @@ async function rowToHistoryEntry(row, repoDir = null, opts = {}) {
     branch: feature,
     sourceBranch: source,
     guardrailsId: row.guardrails_id ?? null,
+    startedBy: row.started_by ?? null,
     pauseReason: row.pause_reason ?? null,
     pauseDetail: row.pause_detail ?? null,
     retainedWork: retainedWorkFor(row),
@@ -1727,7 +1755,7 @@ export async function listPipelines(projectDir, opts = {}, workspaceKey) {
   const dirById = await runDirIndex(pipelinesDir);
   const rows = getDb().prepare(`
     SELECT id, project_key, target, title, status, started_at, updated_at, total_cost_usd, total_active_ms,
-           branch, workspace_meta, guardrails_id, pr_url,
+           branch, workspace_meta, guardrails_id, started_by, pr_url,
            json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseReason') AS pause_reason,
            json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseDetail') AS pause_detail
     FROM pipelines
@@ -1756,7 +1784,7 @@ export async function listPipelines(projectDir, opts = {}, workspaceKey) {
 export async function listAllPipelines(opts = {}, { batchSize = 16 } = {}) {
   const rows = getDb().prepare(`
     SELECT id, project_key, workspace_key, target, title, status, started_at, updated_at,
-           total_cost_usd, total_active_ms, branch, workspace_meta, guardrails_id, pr_url,
+           total_cost_usd, total_active_ms, branch, workspace_meta, guardrails_id, started_by, pr_url,
            json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseReason') AS pause_reason,
            json_extract(CASE WHEN json_valid(resume_point) THEN resume_point END, '$.pauseDetail') AS pause_detail
     FROM pipelines
@@ -1938,6 +1966,7 @@ function rowToState(row) {
     stepper: j(row.stepper, null),
     tools: j(row.tools, null),
     guardrailsId: row.guardrails_id ?? null,
+    startedBy: row.started_by ?? null,
     // v31 provenance: set when a schedule started this run (NULL = started by hand).
     scheduledFor: row.scheduled_for ?? null,
     scheduleId: row.schedule_id ?? null,
@@ -1957,6 +1986,8 @@ function rowToState(row) {
   // too, so a deep-linked History detail no longer waits for the LIST row.
   const rp = j(row.resume_point, null);
   state.pauseReason = typeof rp?.pauseReason === 'string' ? rp.pauseReason : null;
+  // Who paused it (run-harness _recordAction): { kind, by, at } or null.
+  state.lastAction = rp && rp.lastAction && typeof rp.lastAction.by === 'string' ? { ...rp.lastAction } : null;
   state.pauseDetail = typeof rp?.pauseDetail === 'string' ? rp.pauseDetail : null;
   const outcome = j(row.outcome, null);
   if (outcome) {
@@ -2008,6 +2039,7 @@ function buildAuditMarkdown(row) {
     `- **id**: ${row.id}\n` +
     `- **project**: ${(readStoreMeta(row.project_key)?.path) ?? ''}\n` +
     `- **started**: ${row.started_at ?? ''}\n` +
+    (actorLabel(row.started_by) ? `- **started by**: ${actorLabel(row.started_by)}\n` : '') +
     `- **prompt file**: prompt.md\n\n` +
     `## Prompt\n\n` +
     (row.prompt && row.prompt.trim() ? row.prompt.trim() + '\n' : '_(empty prompt)_\n') +

package/src/core/ask/clone-deps.mjs

@@ -0,0 +1,25 @@
+// src/core/ask/clone-deps.mjs
+// Binds clone-proposal.mjs to the real projects folder and registry. The MCP child gets
+// `clones.validateChange` (validate only, for the model's self-correction; it never sees a
+// GitHub credential, so its card has no GitHub line); the parent turn re-validates with
+// `validateCloneProposal`, whose card names how the clone authenticates.
+import { getProjectsRoot } from '../settings.mjs';
+import { listProjects } from '../projects.mjs';
+import { githubMode } from '../deployment.mjs';
+import { createCloneValidator, githubLabel } from './clone-proposal.mjs';
+
+/** The parent's validator: the card carries the GitHub line (deployment.mjs, never a secret). */
+export const validateCloneProposal = createCloneValidator({
+  projectsRoot: () => getProjectsRoot(),
+  listProjects: () => listProjects(),
+  github: (host) => githubLabel(githubMode(process.env), { host, appId: (process.env.WORCA_GH_APP_ID || '').trim() || null }),
+});
+
+/** The MCP child's bundle. */
+export function defaultCloneDeps() {
+  return {
+    clones: {
+      validateChange: createCloneValidator({ projectsRoot: () => getProjectsRoot(), listProjects: () => listProjects() }),
+    },
+  };
+}

package/src/core/ask/clone-proposal.mjs

@@ -0,0 +1,79 @@
+// src/core/ask/clone-proposal.mjs
+// The ONE validator behind mcp__worca__propose_clone_project, and the event/notice text of the
+// clone card (docs/deploy-railway.md "First project"). Pure: the projects root, the registered
+// projects and the GitHub description are injected (clone-deps.mjs binds the real ones), so the
+// MCP child validates for the model's self-correction and the parent turn re-validates
+// authoritatively and mints the card — the model-proposal.mjs split. Nothing here clones:
+// applying the card starts ui/server.mjs's clone job, behind the user's click.
+import { planClone, CloneError } from '../clone-project.mjs';
+
+const str = (v) => (typeof v === 'string' ? v.trim() : '');
+// eslint-disable-next-line no-control-regex
+const BREAKS_RE = /[\x00-\x1f\x7f-\x9f\u2028\u2029]/g;
+const clip = (v, n) => String(v ?? '').replace(BREAKS_RE, ' ').slice(0, n);
+
+/** How the clone authenticates, in words for the card. `mode` = githubMode() (deployment.mjs). */
+export function githubLabel(mode, { host = 'github.com', appId = null } = {}) {
+  if (host !== 'github.com') return `none (${host} is not GitHub): public repositories only`;
+  if (mode === 'app') return `GitHub App${appId ? ` ${appId}` : ''} (a read-only token for this clone)`;
+  if (mode === 'split') return 'the read token (WORCA_GH_READ_TOKEN)';
+  if (mode === 'single') return 'the deployment token (GH_TOKEN)';
+  return 'none: public repositories only';
+}
+
+/**
+ * @param {object} r
+ * @param {() => string} r.projectsRoot         the effective projects folder
+ * @param {() => Promise<Array>} r.listProjects registered projects ({name, path})
+ * @param {object} [r.env]                      for WORCA_CLONE_ALLOW
+ * @param {(host:string) => string|null} [r.github]  the card's GitHub line (null in the MCP child)
+ * @param {(p:string) => boolean} [r.exists]
+ */
+export function createCloneValidator(r) {
+  /** @returns {Promise<{ok:true, card:object}|{ok:false, errors:string[]}>} */
+  return async function validateCloneProposal(input) {
+    const inp = input && typeof input === 'object' && !Array.isArray(input) ? input : {};
+    let plan;
+    try {
+      plan = planClone({ url: inp.url, branch: str(inp.branch) || null, name: str(inp.name) || null },
+        { projectsRoot: r.projectsRoot(), env: r.env || process.env, ...(r.exists ? { exists: r.exists } : {}) });
+    } catch (err) {
+      return { ok: false, errors: [err instanceof CloneError ? err.message : String(err && err.message ? err.message : err)] };
+    }
+    const projects = await r.listProjects();
+    if ((projects || []).some((p) => p && typeof p.name === 'string' && p.name.toLowerCase() === plan.name.toLowerCase())) {
+      return { ok: false, errors: [`a project named "${plan.name}" already exists — pass another name`] };
+    }
+    const note = clip(str(inp.note), 200);
+    const github = typeof r.github === 'function' ? r.github(plan.host) : null;
+    return { ok: true, card: {
+      type: 'clone', kind: 'clone',
+      summary: `Clone ${plan.owner}/${plan.repo} as project ${plan.name}`,
+      url: plan.url, branch: plan.branch, name: plan.name, dir: plan.dir,
+      ...(github ? { github } : {}),
+      ...(note ? { note } : {}),
+      change: { url: plan.url, branch: plan.branch, name: plan.name },
+    } };
+  };
+}
+
+const eventText = (s, n) => clip(s, n).replace(/"/g, "'").replace(/\[(\/?)worca context\]/gi, '($1worca context)');
+
+/** `[worca event] …` — the synthetic turn's prompt after the user acted on a clone card, or its clone ended. */
+export function cloneEventPrompt({ cardId, state, card = {}, result = null }) {
+  const summary = eventText(card.summary, 200);
+  if (state === 'declined') return `[worca event] clone card ${cardId} declined; "${summary}"`;
+  if (state === 'failed') {
+    return `[worca event] clone card ${cardId} failed${result?.code ? ` (${eventText(result.code, 40)})` : ''}: ${eventText(result?.error || 'unknown error', 300)}; "${summary}"`;
+  }
+  const where = result?.project ? `; project ${eventText(result.project.name, 100)} at ${eventText(result.project.path, 300)}` : '';
+  return `[worca event] clone card ${cardId} applied: cloned and registered${where}; "${summary}"`;
+}
+
+/** The user-row notice above the event turn. */
+export function cloneNoticeText({ state, card = {}, result = null }) {
+  const s = clip(card.summary, 160);
+  if (state === 'declined') return `Declined — ${s}`;
+  if (state === 'failed') return `Could not clone — ${s}: ${clip(result?.error || 'unknown error', 200)}`;
+  return `Cloned — ${s}${result?.project?.path ? ` · ${clip(result.project.path, 200)}` : ''}`;
+}

package/src/core/ask/events.mjs

@@ -126,6 +126,7 @@ export function labelForTool(name, input = {}, attachmentNames = {}) {
   const id = typeof input?.id === 'string' ? input.id : '';
   switch (n) {
     case 'list_runs': return 'Finding runs';
+    case 'list_people': return 'Looking up who ran what';
     case 'get_run':
     case 'get_run_diff': return id ? `Reading run ${id.slice(0, 12)}` : 'Reading run';
     case 'list_workflows': return 'Looking at workflows';
@@ -170,6 +171,7 @@ export function labelForTool(name, input = {}, attachmentNames = {}) {
     case 'test_provider': return input?.provider ? `Testing ${String(input.provider).slice(0, 20)}` : 'Testing a provider';
     case 'list_copilot_models': return 'Listing Copilot models';
     case 'propose_model_change': return 'Proposing a model change';
+    case 'propose_clone_project': return 'Proposing a project clone';
     default: return `Using ${n}`;
   }
 }
@@ -246,6 +248,7 @@ export function createTurnReducer({
   onPolicyProposal = null,       // propose_policy_change RESULT (team policy card; same split)
   onScheduleProposal = null,     // propose_schedule_change RESULT (schedule card; the parent re-validates the input)
   onModelProposal = null,        // propose_model_change RESULT (model card; same split)
+  onCloneProposal = null,        // propose_clone_project RESULT (clone card; same split)
   onScheduleMutation = null,     // a direct schedule write succeeded in the MCP child
   onTrackRun = null,
   onCommentMutation = null,
@@ -606,6 +609,13 @@ export function createTurnReducer({
           if (ret && typeof ret.then === 'function') pendingHooks.push(ret.then(() => {}, () => { reducerErrors += 1; }));
         } catch { reducerErrors += 1; }
       }
+      if (b.name === 'mcp__worca__propose_clone_project' && typeof onCloneProposal === 'function') {
+        // Same split as the model card: the parent re-validates the INPUT and adds how GitHub is reached (clone-proposal.mjs).
+        try {
+          const ret = onCloneProposal({ toolUseId: b.id, input: fullInputs.get(b.id) ?? {}, text, isError: !!c.is_error });
+          if (ret && typeof ret.then === 'function') pendingHooks.push(ret.then(() => {}, () => { reducerErrors += 1; }));
+        } catch { reducerErrors += 1; }
+      }
       if (b.name === 'mcp__worca__track_run' && typeof onTrackRun === 'function') {
         // The parent owns the runs Map, the link rows and the followers: it re-resolves the id itself (D4).
         try {