coxpit 3.8.0 → 4.1.0

package/README.md

@@ -20,6 +20,10 @@ Your machines. Your auth. Your code never leaves your network.
 - **Multi-machine** — register remote machines over SSH (Tailscale/LAN); probe reachability (git·tmux), run fleets there.
 - **Safe stops** — stop kills the whole process group; task close stops and cleans every worktree/branch.
 - **Design Mode** — drag the `⌖ coxpit inspect` bookmarklet to your bar, click it on your running app, click any element: its selector, HTML and computed styles are captured and injected into the agents' prompt as design context.
+- **Self-orchestrating agents** — every local run can spawn its own sub-agents by writing `.coxpit/spawn.json` in its worktree (works under default permissions — no network, no escalation). The daemon launches each subtask as an isolated sub-run and maintains `.coxpit/subtasks.json` with live status. Orchestration moves inside the agent's own reasoning loop.
+- **Start from GitHub** — paste an issue/PR URL and the task form drafts itself from its title and body (gh CLI for private repos, public API otherwise). You review, pick a provider, Run fleet.
+- **Share a run** — one click mints a read-only snapshot link (timeline + diff, and the rendered docs, no auth, no actions). Show your fleet's work without opening your cockpit.
+- **The library** — a run's changed documents (Markdown/HTML) are snapshotted when it settles, so the Rendered view survives merge and Close task. Pick a model per launch (any name your CLI accepts), and a close guard warns before it deletes unmerged, unexported output.
 
 External tools are spawned, never vendored: `git`, `tmux`, your agent CLI. No editor bundled — terminal-first.
 
@@ -74,6 +78,7 @@ Your keys and login never touch coxpit's config or database.
 | `COXPIT_AGENT_PERM` | `acceptEdits` | Claude Code headless permission mode |
 | `COXPIT_CODEX_BIN` | `codex` | Codex CLI command (optional second provider) |
 | `COXPIT_CODEX_SANDBOX` | `workspace-write` | Codex sandbox policy (`danger-full-access` for full autonomy) |
+| `COXPIT_AGENT_ORCH` | on | `0` disables agent self-orchestration (the `.coxpit/spawn.json` protocol + prompt note) |
 | `COXPIT_WEBHOOK_URL` | — | POSTs `{event:"run.settled",run:{...}}` when a run finishes — wire it to Telegram, Slack, anything |
 | `COXPIT_PUBLIC_URL` | — | if set, the webhook payload adds `url: <base>/?run=<id>` — tap it on your phone and the board opens that run |
 
@@ -105,7 +110,7 @@ One daemon, one SQLite file, zero external services. Machines are reached over S
 
 ## Status
 
-`v3.0` — fleet, compare/merge, terminal, Design Mode, run destinations (merge · export · PR), swarm (plan fan-out + integrate with conflict-resolving agents), AI review, and sessions (work/ask + notifications) — all shipped and e2e-tested. Roadmap: ROADMAP.md.
+`v4.1` — fleet, two providers (Claude Code · Codex) with per-launch model choice, compare/merge + AI review + doc mode with settle-time snapshots, terminal (full-screen, session tabs, mobile input bar), swarm (plan fan-out · integrate · agent self-orchestration), sessions (steer/ask · resume), mobile board with deep links, GitHub import, read-only share links that render documents, a close guard, and per-repo base branch override — all shipped and e2e-tested (35 checks). Roadmap: ROADMAP.md.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coxpit",
-  "version": "3.8.0",
+  "version": "4.1.0",
   "description": "Self-hosted cockpit for running a fleet of AI coding agents across your own machines — parallel worktree runs, live board, compare & merge, web terminal, design capture.",
   "type": "module",
   "license": "MIT",

package/src/auth.ts

@@ -3,7 +3,9 @@ import { config } from './config';
 
 // /api/design/capture · /design/bookmarklet.js 는 외부 앱(북마클릿)에서 오므로
 // basic 헤더를 못 싣는다 — 라우트 자체가 캡처 키(?k=)를 검증한다.
-const EXEMPT = new Set(['/api/health', '/api/design/capture', '/design/bookmarklet.js']);
+// /api/agent/subtasks 는 에이전트 Bearer 토큰(라우트 자체 검증), /share/* 는 토큰 URL 이 곧 능력.
+const EXEMPT = new Set(['/api/health', '/api/design/capture', '/design/bookmarklet.js', '/api/agent/subtasks']);
+const EXEMPT_PREFIX = ['/share/'];
 
 /**
  * 인증 게이트 — 현재 basic. 플러그형 좌석: 배포 시 앞단에 Cloudflare Access / Tailscale 을
@@ -13,6 +15,7 @@ export async function authGate(req: FastifyRequest, reply: FastifyReply): Promis
   if (config.auth.disabled) return;
   const path = req.url.split('?')[0] ?? '';
   if (EXEMPT.has(path)) return;
+  if (EXEMPT_PREFIX.some((p) => path.startsWith(p))) return;
 
   const h = req.headers.authorization ?? '';
   if (h.startsWith('Basic ') && config.auth.pass !== '') {

package/src/board.ts

@@ -164,6 +164,15 @@ export const BOARD_HTML = /* html */ `<!doctype html>
   .ev{display:flex;gap:9px;align-items:baseline;min-width:0}
   .ev .k{color:var(--brand);min-width:78px;flex:none;opacity:.85}
   .ev .t{color:var(--muted);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;flex:1}
+  /* ── closed card — 죽은 카드는 확실히 죽어 보이게(빗금 + CLOSED 스탬프) ── */
+  .card.closed{opacity:.6;filter:saturate(.45)}
+  .card.closed .log{position:relative}
+  .card.closed .log::after{content:'';position:absolute;inset:0;pointer-events:none;
+    background:repeating-linear-gradient(135deg,transparent 0 9px,rgba(255,255,255,.035) 9px 11px)}
+  .card.closed .log::before{content:'CLOSED';position:absolute;top:50%;left:50%;z-index:1;
+    transform:translate(-50%,-50%) rotate(-7deg);font-family:var(--mono);font-size:15px;
+    letter-spacing:.34em;color:var(--faint);border:1px solid var(--line-hi);
+    border-radius:6px;padding:4px 14px;background:rgba(11,13,18,.72)}
   /* ── select mode (integrate) ── */
   .toolbar{display:flex;justify-content:flex-end;gap:8px;margin-bottom:12px}
   .card.selmode{cursor:copy}
@@ -291,6 +300,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
   .cmp-review p{margin:0 0 8px}
 
   /* ── doc mode (rendered output) ─────────── */
+  .doc-src{font-family:var(--mono);font-size:10.5px;color:var(--faint);margin-bottom:10px}
   .doc-h{font-family:var(--mono);font-size:10.5px;color:var(--brand);padding:8px 0 4px;
     border-bottom:1px solid var(--line);margin-bottom:8px;word-break:break-all}
   .doc-md{font-size:13px;line-height:1.65;color:var(--muted);margin-bottom:16px;font-family:var(--sans)}
@@ -378,6 +388,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
       <div class="row">
         <button type="button" class="btn-ghost sm" id="repoBrowse" style="flex:1">Browse…</button>
         <button type="button" class="btn-ghost sm" id="repoManual" style="flex:0 0 auto" title="type an absolute path">Path</button>
+        <button type="button" class="btn-ghost sm" id="repoBranch" style="flex:0 0 auto" title="change the base branch — merges, Sync base and PRs all target it">⎇</button>
         <button type="button" class="btn-ghost sm" id="repoRemove" style="flex:0 0 auto" title="remove selected repository from coxpit">×</button>
       </div>
       <form id="repoForm" hidden>
@@ -399,10 +410,14 @@ export const BOARD_HTML = /* html */ `<!doctype html>
         <div id="panelTask" style="display:flex;flex-direction:column;gap:8px">
           <input id="taskTitle" placeholder="Task title" />
           <textarea id="taskPrompt" placeholder="Prompt — target files, constraints, how to verify"></textarea>
+          <button type="button" class="btn-ghost sm" id="ghImport">From GitHub issue / PR…</button>
           <div class="seg" id="provSeg" role="group" aria-label="agent provider">
             <button type="button" class="seg-opt on" data-agent="claude-code">Claude</button>
             <button type="button" class="seg-opt" data-agent="codex">Codex</button>
           </div>
+          <p class="flabel">model · optional</p>
+          <input id="taskModel" placeholder="CLI default" list="modelHist" autocomplete="off" />
+          <datalist id="modelHist"></datalist>
           <p class="flabel">design capture · optional</p>
           <select id="taskCapture"><option value="">no design capture</option></select>
         </div>
@@ -478,6 +493,7 @@ export const BOARD_HTML = /* html */ `<!doctype html>
       <button class="btn-ghost sm" id="mCompare">Compare runs</button>
       <button class="btn-ghost sm" id="mExport">Export files…</button>
       <button class="btn-ghost sm" id="mSync">Sync base</button>
+      <button class="btn-ghost sm" id="mShare" title="create a read-only share link (no auth, snapshot view)">Share</button>
       <span class="spacer"></span>
       <button class="btn-danger sm" id="mStop">Stop</button>
       <button class="btn-ghost sm" id="mCleanup">Cleanup</button>
@@ -548,6 +564,36 @@ export const BOARD_HTML = /* html */ `<!doctype html>
   <button class="btn-ghost sm" id="selCancel">Cancel</button>
 </div>
 
+<div class="overlay" id="ghOverlay">
+  <div class="cfm">
+    <div class="cfm-b">
+      <div class="m">Start from a GitHub issue or pull request</div>
+      <div class="s">Fetches the title and body into the task form — you review, pick a provider, then Run fleet. Private repos need the gh CLI signed in on the daemon machine.</div>
+      <p class="flabel" style="margin-top:12px">issue / PR url</p>
+      <input id="ghUrl" placeholder="https://github.com/owner/repo/issues/123" />
+    </div>
+    <div class="cfm-f">
+      <button class="btn-ghost sm" id="ghCancel">Cancel</button>
+      <button class="btn sm" id="ghOk">Fetch</button>
+    </div>
+  </div>
+</div>
+
+<div class="overlay" id="brOverlay">
+  <div class="cfm">
+    <div class="cfm-b">
+      <div class="m">Base branch for this repository</div>
+      <div class="s">Merge, Sync base and PR mode all target this branch. Set it to match your repo's flow (e.g. <span style="color:var(--brand);font-family:var(--mono)">develop</span>). Must already exist in the repo.</div>
+      <p class="flabel" style="margin-top:12px">branch name</p>
+      <input id="brInput" placeholder="main" />
+    </div>
+    <div class="cfm-f">
+      <button class="btn-ghost sm" id="brCancel">Cancel</button>
+      <button class="btn sm" id="brOk">Save</button>
+    </div>
+  </div>
+</div>
+
 <div class="overlay" id="expOverlay">
   <div class="cfm">
     <div class="cfm-b">
@@ -726,6 +772,7 @@ function humanize(e){
     }
     if (o.type === 'assistant' && o.text) return { k:'said', t:o.text };
     if (o.type === 'result') return { k:'done', t:o.result || 'finished' };
+    if (kind === 'meta' && o.subtask) return { k:'swarm', t:'↳ spawned task #'+o.subtask+' — '+String(o.title||'').slice(0,60)+' ('+((o.runs||[]).map(x=>'r'+x).join(' '))+')' };
     if (kind === 'meta') return { k:'start', t:'worktree '+String(o.worktree||'').split('/').slice(-2).join('/') };
     return { k:kind, t:payload.slice(0,140) };
   }catch{
@@ -844,13 +891,15 @@ function cardHTML(r){
   const evs = humanLines(r.events).slice(-8).map(h =>
     '<div class="ev"><span class="k">'+esc(h.k)+'</span><span class="t">'+esc(h.t).slice(0,140)+'</span></div>'
   ).join('') || '<div class="ev"><span class="t" style="color:var(--faint)">waiting…</span></div>';
-  const selCls = (selectMode?' selmode':'') + (selected.has(r.id)?' selected':'');
+  const selCls = (selectMode?' selmode':'') + (selected.has(r.id)?' selected':'') + (closed?' closed':'');
   return '<div class="card'+selCls+'" id="card-'+r.id+'">'
     + '<div class="card-h"><span class="rid">r'+r.id+'</span><span class="title">'+title+'</span>'
     + '<span class="selbox">✓</span>'+chipHTML(r.status)+'</div>'
     + '<div class="meta"><span>branch <b>'+esc(r.branch||'—')+'</b></span>'
     + '<span>files <b>'+(r.filesChanged??0)+'</b></span>'
     + '<span>'+esc(r.agent||'')+'</span>'
+    + (r.model ? '<span title="model">⚙ '+esc(r.model)+'</span>' : '')
+    + (task && task.parentRunId ? '<span title="spawned by agent r'+task.parentRunId+'">↳ by r'+task.parentRunId+'</span>' : '')
     + (r.sessionId && ['done','failed','stopped'].includes(r.status)
         ? '<span class="resumable" title="agent session preserved — open the run and Send a next instruction to continue">↻ resumable</span>' : '')
     + (r.prUrl ? '<a href="'+esc(r.prUrl)+'" target="_blank" rel="noopener" style="margin-left:auto">PR ↗</a>' : '')
@@ -923,6 +972,26 @@ $('repoRemove').addEventListener('click', async ()=>{
   if (res.ok){ toast('repo removed', 'ok'); hydrate(); }
   else toast('remove: '+(j.detail||res.status), 'error');
 });
+/* ── 기본 브랜치 변경 ── */
+$('repoBranch').addEventListener('click', ()=>{
+  const rid = $('taskRepo').value;
+  if (!rid){ toast('no repository selected', 'error'); return; }
+  const repo = repos.find(r=>String(r.id)===String(rid));
+  $('brInput').value = repo ? repo.defaultBranch : '';
+  $('brOverlay').classList.add('open'); $('brInput').focus();
+});
+$('brCancel').addEventListener('click', ()=>$('brOverlay').classList.remove('open'));
+$('brOverlay').addEventListener('click',(e)=>{ if(e.target===$('brOverlay')) $('brOverlay').classList.remove('open'); });
+async function brSave(){
+  const rid = $('taskRepo').value; const branch = $('brInput').value.trim();
+  if (!rid || !branch) return;
+  const res = await fetch('/api/repos/'+rid,{method:'PATCH',headers:{'content-type':'application/json'},body:JSON.stringify({defaultBranch:branch})});
+  const j = await res.json().catch(()=>({}));
+  if (res.ok){ $('brOverlay').classList.remove('open'); toast('base branch → '+j.defaultBranch, 'ok'); hydrate(); }
+  else toast('branch: '+(j.error||res.status), 'error');
+}
+$('brOk').addEventListener('click', brSave);
+$('brInput').addEventListener('keydown',(e)=>{ if(e.key==='Enter') brSave(); });
 $('repoManual').addEventListener('click', ()=>{
   const f = $('repoForm'); f.hidden = !f.hidden;
   if (!f.hidden) $('repoPath').focus();
@@ -1009,17 +1078,31 @@ function paintModal(){
 async function loadDiff(){
   if (openRunId==null || docMode) return;
   const pre = $('mDiff'); if (!pre) return;
+  const rid = openRunId;
   pre.textContent = 'loading…'; $('mStat').textContent='';
   try{
-    const d = await fetch('/api/runs/'+openRunId+'/diff').then(x=>x.json());
-    if (!d.ok){ pre.textContent = d.stat||'no worktree'; return; }
+    const d = await fetch('/api/runs/'+rid+'/diff').then(x=>x.json());
+    if (!d.ok){
+      pre.textContent = d.stat||'no worktree';
+      // worktree 는 없지만 스냅샷 문서가 있으면 Rendered 토글 노출(머지·Close 후 뷰어)
+      maybeShowDocsToggle(rid);
+      return;
+    }
     const files = d.stat ? d.stat.split('\\n').filter(Boolean).length : 0;
     $('mStat').textContent = files ? '· '+files+' file'+(files>1?'s':'') : '· clean';
-    // 변경분에 문서(md/html)가 있으면 Rendered 토글 노출
-    $('mDocsTgl').hidden = !/\\.(md|markdown|html?|htm)$/im.test(d.stat||'');
     pre.innerHTML = diffHTML(d.diff||'');
+    // 변경분에 문서(md/html)가 있으면 즉시 노출, 없으면 스냅샷 확인
+    if (/\\.(md|markdown|html?|htm)$/im.test(d.stat||'')) $('mDocsTgl').hidden = false;
+    else maybeShowDocsToggle(rid);
   }catch{ pre.textContent = 'diff failed'; }
 }
+/* worktree 에 라이브 문서가 없을 때만 — 스냅샷이라도 있으면 토글을 켠다 */
+async function maybeShowDocsToggle(rid){
+  try{
+    const j = await fetch('/api/runs/'+rid+'/docs').then(x=>x.json());
+    if (rid===openRunId && (j.docs||[]).length) $('mDocsTgl').hidden = false;
+  }catch{}
+}
 /* ── doc 모드 — diff 대신 렌더된 문서 산출물 ── */
 let docMode = false;
 function docsHTML(docs){
@@ -1034,7 +1117,9 @@ async function paintDocs(){
   $('mDiffWrap').innerHTML = '<span style="color:var(--faint)">rendering…</span>';
   try{
     const d = await fetch('/api/runs/'+openRunId+'/docs').then(x=>x.json());
-    $('mDiffWrap').innerHTML = docsHTML(d.docs||[]);
+    const src = d.source==='snapshot'
+      ? '<div class="doc-src">worktree gone — snapshot taken at settle</div>' : '';
+    $('mDiffWrap').innerHTML = src + docsHTML(d.docs||[]);
   }catch{ $('mDiffWrap').textContent = 'docs failed'; }
 }
 function setDocMode(on){
@@ -1106,7 +1191,7 @@ $('grid').addEventListener('click',(e)=>{
 });
 $('mClose').addEventListener('click', closeModal);
 $('overlay').addEventListener('click',(e)=>{ if(e.target===$('overlay')) closeModal(); });
-document.addEventListener('keydown',(e)=>{ if(e.key==='Escape'){ closeDropdowns(); cfmClose(false); $('brwOverlay').classList.remove('open'); $('expOverlay').classList.remove('open'); closeTerm(); closeModal(); cmpTaskId=null; $('cmpOverlay').classList.remove('open'); } });
+document.addEventListener('keydown',(e)=>{ if(e.key==='Escape'){ closeDropdowns(); cfmClose(false); $('brwOverlay').classList.remove('open'); $('expOverlay').classList.remove('open'); $('ghOverlay').classList.remove('open'); $('brOverlay').classList.remove('open'); closeTerm(); closeModal(); cmpTaskId=null; $('cmpOverlay').classList.remove('open'); } });
 $('mRefreshDiff').addEventListener('click', loadDiff);
 $('mExport').addEventListener('click', ()=>{
   if (openRunId==null) return;
@@ -1176,7 +1261,18 @@ $('mCloseTask').addEventListener('click', async ()=>{
   const yes = await confirmUI('Close this task?',
     { sub: 'Stops any live runs and removes every worktree and branch of the task.', danger: true, okLabel: 'Close task' });
   if (!yes) return;
-  await fetch('/api/tasks/'+r.taskId+'/close',{method:'POST'});
+  const close = (force)=>fetch('/api/tasks/'+r.taskId+'/close',{method:'POST',
+    headers:{'content-type':'application/json'}, body:JSON.stringify({force})});
+  let res = await close(false);
+  if (res.status===409){
+    const j = await res.json().catch(()=>({}));
+    const risk = (j.atRisk||[]).map(a=>'r'+a.runId+' · '+a.filesChanged+' file'+(a.filesChanged>1?'s':'')).join(' · ');
+    const ok = await confirmUI('Close and delete unmerged output?',
+      { danger:true, sub: risk+' — not merged, not exported. Worktrees are deleted on close.', okLabel:'Close anyway' });
+    if (!ok) return;
+    res = await close(true);
+  }
+  if (!res.ok){ toast('close failed ('+res.status+')', 'error'); return; }
   toast('task closed — all runs cleaned', 'ok');
   closeModal(); hydrate();
 });
@@ -1492,11 +1588,28 @@ $('taskForm').addEventListener('submit', async (e)=>{
     body:JSON.stringify({repoId,title,prompt:$('taskPrompt').value,designCaptureId:capId})}).then(x=>x.json());
   if (!t.ok){ toast('task create failed', 'error'); return; }
   tasks.set(t.task.id, t.task);
+  const model = $('taskModel').value.trim();
   await fetch('/api/tasks/'+t.task.id+'/run',{method:'POST',headers:{'content-type':'application/json'},
-    body:JSON.stringify({count:Number($('taskCount').value)||1, real: $('taskReal').checked, agent: selAgent})});
+    body:JSON.stringify({count:Number($('taskCount').value)||1, real: $('taskReal').checked, agent: selAgent, model})});
+  if (model) rememberModel(model);
   $('taskTitle').value=''; $('taskPrompt').value='';
 });
 
+/* ── model 최근값 기억(기기별, 최대 5) ── */
+function rememberModel(m){
+  try{
+    const h = JSON.parse(localStorage.getItem('coxpit.models')||'[]');
+    localStorage.setItem('coxpit.models', JSON.stringify([m, ...h.filter(x=>x!==m)].slice(0,5)));
+  }catch{}
+  paintModelHist();
+}
+function paintModelHist(){
+  let h = [];
+  try{ h = JSON.parse(localStorage.getItem('coxpit.models')||'[]'); }catch{}
+  $('modelHist').innerHTML = h.map(m=>'<option value="'+escA(m)+'"></option>').join('');
+}
+paintModelHist();
+
 /* ── agent mode segmented control (mirrors hidden #taskReal) ── */
 const segOpts = Array.from(document.querySelectorAll('#modeSeg .seg-opt'));
 function setMode(real, persist){
@@ -1530,6 +1643,38 @@ let savedAgent = null;
 try { savedAgent = localStorage.getItem('coxpit.agent'); } catch {}
 if (savedAgent === 'codex') setProvider('codex', false);
 
+/* ── GitHub 이슈/PR → 태스크 초안 ── */
+$('ghImport').addEventListener('click', ()=>{ $('ghUrl').value=''; $('ghOverlay').classList.add('open'); $('ghUrl').focus(); });
+$('ghCancel').addEventListener('click', ()=>$('ghOverlay').classList.remove('open'));
+$('ghOverlay').addEventListener('click',(e)=>{ if(e.target===$('ghOverlay')) $('ghOverlay').classList.remove('open'); });
+async function ghFetch(){
+  const url = $('ghUrl').value.trim();
+  if (!url) return;
+  $('ghOk').disabled = true; $('ghOk').textContent = 'Fetching…';
+  try{
+    const res = await fetch('/api/tasks/from-github',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({url})});
+    const j = await res.json().catch(()=>({}));
+    if (!res.ok){ toast('github: '+(j.error||res.status), 'error'); return; }
+    $('taskTitle').value = j.title; $('taskPrompt').value = j.prompt;
+    $('ghOverlay').classList.remove('open');
+    toast('drafted from GitHub — review, then Run fleet', 'ok');
+  } finally { $('ghOk').disabled = false; $('ghOk').textContent = 'Fetch'; }
+}
+$('ghOk').addEventListener('click', ghFetch);
+$('ghUrl').addEventListener('keydown',(e)=>{ if(e.key==='Enter') ghFetch(); });
+
+/* ── 읽기 전용 공유 링크 ── */
+$('mShare').addEventListener('click', async ()=>{
+  if (openRunId==null) return;
+  const res = await fetch('/api/runs/'+openRunId+'/share',{method:'POST'});
+  const j = await res.json().catch(()=>({}));
+  if (!res.ok){ toast('share: '+(j.error||res.status), 'error'); return; }
+  const url = location.origin + j.url;
+  let copied = false;
+  try{ await navigator.clipboard.writeText(url); copied = true; }catch{}
+  toast((j.existing?'share link (existing)':'share link created')+(copied?' — copied':'')+': '+url, 'ok');
+});
+
 /* ── mobile drawer ── */
 const asideEl = document.querySelector('aside');
 function setDrawer(on){ asideEl.classList.toggle('open', on); $('scrim').classList.toggle('on', on); }

package/src/config.ts

@@ -75,6 +75,9 @@ export const config = {
     // 완전 자율은 bypassPermissions.
     perm: process.env.COXPIT_AGENT_PERM ?? 'acceptEdits',
   },
+  // 에이전트 셀프 오케스트레이션 — real+로컬 run 에 COXPIT_API/COXPIT_TOKEN env 와
+  // 능력 고지를 준다(에이전트가 /api/agent/subtasks 로 서브런 발사). '0' 으로 끔.
+  agentOrch: process.env.COXPIT_AGENT_ORCH !== '0',
   codex: {
     // 두 번째 프로바이더 — OpenAI Codex CLI (선택 설치). providers.ts 의 시임.
     bin: process.env.COXPIT_CODEX_BIN ?? 'codex',

package/src/db/index.ts

@@ -69,9 +69,25 @@ export async function ensureSchema(): Promise<void> {
       payload TEXT NOT NULL DEFAULT '',
       ts INTEGER DEFAULT (unixepoch())
     );
+    CREATE TABLE IF NOT EXISTS share_links (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      run_id INTEGER NOT NULL,
+      token TEXT NOT NULL UNIQUE,
+      created_at INTEGER DEFAULT (unixepoch())
+    );
+    CREATE TABLE IF NOT EXISTS doc_snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      run_id INTEGER NOT NULL,
+      path TEXT NOT NULL,
+      kind TEXT NOT NULL,
+      content TEXT NOT NULL DEFAULT '',
+      created_at INTEGER DEFAULT (unixepoch())
+    );
   `);
   // 기존 DB 마이그레이션(멱등)
   try { await client.execute('ALTER TABLE tasks ADD COLUMN design_capture_id INTEGER'); } catch { /* exists */ }
   try { await client.execute("ALTER TABLE agent_runs ADD COLUMN session_id TEXT NOT NULL DEFAULT ''"); } catch { /* exists */ }
   try { await client.execute("ALTER TABLE agent_runs ADD COLUMN pr_url TEXT NOT NULL DEFAULT ''"); } catch { /* exists */ }
+  try { await client.execute('ALTER TABLE tasks ADD COLUMN parent_run_id INTEGER'); } catch { /* exists */ }
+  try { await client.execute("ALTER TABLE agent_runs ADD COLUMN model TEXT NOT NULL DEFAULT ''"); } catch { /* exists */ }
 }

package/src/db/schema.ts

@@ -40,6 +40,25 @@ export const tasks = sqliteTable('tasks', {
   prompt: text('prompt').notNull().default(''),
   status: text('status').notNull().default('open'), // open | done
   designCaptureId: integer('design_capture_id'), // 선택 — 프롬프트에 DESIGN CONTEXT 주입
+  parentRunId: integer('parent_run_id'), // 에이전트 셀프 오케스트레이션 — 이 태스크를 발사한 run
+  createdAt: integer('created_at', { mode: 'timestamp' }),
+});
+
+/** 정착·정리 시점에 회수한 문서(md/html) 스냅샷 — worktree 소멸 후에도 렌더 뷰 유지. */
+export const docSnapshots = sqliteTable('doc_snapshots', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  runId: integer('run_id').notNull(),
+  path: text('path').notNull(),
+  kind: text('kind').notNull(), // 'md' | 'html'
+  content: text('content').notNull().default(''),
+  createdAt: integer('created_at', { mode: 'timestamp' }),
+});
+
+/** 읽기 전용 공유 링크 — run 스냅샷을 무인증으로 보여준다(토큰 = capability). */
+export const shareLinks = sqliteTable('share_links', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  runId: integer('run_id').notNull(),
+  token: text('token').notNull().unique(),
   createdAt: integer('created_at', { mode: 'timestamp' }),
 });
 
@@ -55,6 +74,7 @@ export const agentRuns = sqliteTable('agent_runs', {
   status: text('status').notNull().default('pending'), // pending | running | waiting | done | error
   sessionId: text('session_id').notNull().default(''), // 에이전트 세션(steer 용 --resume 키)
   prUrl: text('pr_url').notNull().default(''), // PR 모드로 올린 pull request URL
+  model: text('model').notNull().default(''), // 런치별 모델 지정(빈값 = CLI 기본)
   filesChanged: integer('files_changed').notNull().default(0),
   startedAt: integer('started_at', { mode: 'timestamp' }),
   endedAt: integer('ended_at', { mode: 'timestamp' }),

package/src/orchestrator.ts

@@ -1,20 +1,21 @@
+import { randomBytes } from 'node:crypto';
 import { posix as ppath } from 'node:path';
 import { createInterface } from 'node:readline';
 import { existsSync } from 'node:fs';
-import { mkdir, copyFile } from 'node:fs/promises';
+import { mkdir, copyFile, readFile, writeFile, rm } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import type { ChildProcess } from 'node:child_process';
 import { eq } from 'drizzle-orm';
 import { config } from './config';
 import { db } from './db';
-import { agentRuns, agentEvents, tasks, repos, machines, designCaptures } from './db/schema';
+import { agentRuns, agentEvents, tasks, repos, machines, designCaptures, docSnapshots } from './db/schema';
 import { runShellOn, spawnShellOn, shq, type MachineTarget } from './exec';
 import { broadcast } from './hub';
 import { getProvider, type Provider } from './providers';
 
 /** 에이전트 실행 커맨드. 드라이런=모의 stream-json + 실제 파일 1건 변경. */
-function agentCommand(provider: Provider, prompt: string, real: boolean): string {
-  if (real) return provider.launchCmd(prompt);
+function agentCommand(provider: Provider, prompt: string, real: boolean, model = ''): string {
+  if (real) return provider.launchCmd(prompt, model || undefined);
   // 모의: init → assistant → (파일 변경) → result. claude stream-json 라인 형태
   // (드라이런은 프로바이더 불문 배관 리허설 — claude 파서가 처리한다).
   return [
@@ -40,6 +41,134 @@ async function setRun(runId: number, patch: Partial<typeof agentRuns.$inferInser
 const liveChildren = new Map<number, ChildProcess>();
 const stoppedRuns = new Set<number>();
 
+// ── 에이전트 셀프 오케스트레이션 ──────────────────────────────
+// run 마다 1회용 토큰을 발급해 에이전트 env 로 준다. 에이전트는 그 토큰으로
+// /api/agent/subtasks 를 호출해 같은 repo 에 독립 서브런을 발사할 수 있다.
+// 인메모리 = 데몬 재시작 시 무효(고아 정산과 같은 수명 철학).
+const agentTokens = new Map<string, number>(); // token -> runId
+
+function issueAgentToken(runId: number): string {
+  for (const [t, r] of agentTokens) if (r === runId) return t; // steer 재사용
+  const tok = randomBytes(16).toString('hex');
+  agentTokens.set(tok, runId);
+  return tok;
+}
+
+/** Bearer 토큰 → runId (없으면 null). server 의 /api/agent/* 가 사용. */
+export function resolveAgentToken(token: string): number | null {
+  return agentTokens.get(token) ?? null;
+}
+
+/** 에이전트 프롬프트에 붙는 능력 고지 — 독립 하위작업을 병렬 서브런으로 뺄 수 있다.
+ * 파일 기반: 기본 권한(claude acceptEdits · codex workspace-write)이 네트워크를 막아도
+ * 파일 쓰기는 되므로, spawn 요청을 워크트리의 .coxpit/spawn.json 으로 받는다. */
+function orchestrationNote(): string {
+  return '\n\n--- COXPIT ORCHESTRATION (optional) ---\n' +
+    'You can parallelize genuinely independent subwork by spawning sub-agents. To spawn, write the file ' +
+    '`.coxpit/spawn.json` in your working directory:\n' +
+    '  {"title": "short title", "prompt": "full agent prompt", "count": 1}\n' +
+    '(or an array of such objects, max 4). The daemon consumes it within ~2s and launches each subtask ' +
+    'as an isolated sub-run of this repository. It keeps `.coxpit/subtasks.json` updated with their live ' +
+    'status — read it to check progress. Prefer doing work yourself; spawn only clearly separable, ' +
+    'file-disjoint tasks. Do not busy-wait on sub-agents.\n' +
+    '--- END COXPIT ORCHESTRATION ---';
+}
+
+/**
+ * 파일 기반 오케스트레이션 워처 — run 이 사는 동안 worktree 의 .coxpit/spawn.json 을
+ * 소비해 서브태스크를 발사하고, .coxpit/subtasks.json 에 현황을 유지한다.
+ * 로컬 run 전용(원격은 데몬이 파일에 못 닿음). 반환된 타이머는 run 종료 시 정리.
+ */
+export function startOrchWatch(runId: number, wtPath: string, real: boolean): NodeJS.Timeout {
+  const dir = ppath.join(wtPath, '.coxpit');
+  let last = '';
+  let busy = false;
+  return setInterval(() => {
+    if (busy) return;
+    busy = true;
+    void (async () => {
+      try {
+        const spawnPath = ppath.join(dir, 'spawn.json');
+        const txt = await readFile(spawnPath, 'utf8').catch(() => null);
+        if (txt !== null) {
+          await rm(spawnPath).catch(() => { /* consumed */ });
+          try {
+            const req = JSON.parse(txt) as unknown;
+            const items = (Array.isArray(req) ? req : [req]) as Array<{ title?: string; prompt?: string; count?: number }>;
+            for (const it of items.slice(0, 4)) {
+              if (typeof it?.title === 'string' && typeof it?.prompt === 'string' && it.title && it.prompt) {
+                await spawnSubtasks(runId, it.title, it.prompt, Number(it.count) || 1, real);
+              }
+            }
+          } catch {
+            await recordEvent(runId, 'error', 'spawn.json was not valid JSON — nothing spawned');
+          }
+        }
+        // 현황 파일 — 내용이 바뀔 때만 다시 쓴다
+        const subs = await listSubtasks(runId);
+        if (subs.length) {
+          const j = JSON.stringify(subs, null, 2);
+          if (j !== last) {
+            last = j;
+            await mkdir(dir, { recursive: true });
+            await writeFile(ppath.join(dir, 'subtasks.json'), j);
+          }
+        }
+      } catch { /* 워처 오류는 조용히 — 다음 틱에 재시도 */ }
+      busy = false;
+    })();
+  }, 1500);
+}
+
+/**
+ * 에이전트가 요청한 서브태스크 생성+발사. 부모 run 의 repo/머신/프로바이더 상속, real 고정
+ * (토큰은 real run 에만 발급되므로). 결과는 부모 타임라인에 meta 이벤트로 남는다.
+ */
+export async function spawnSubtasks(parentRunId: number, title: string, prompt: string, count: number, real = true): Promise<{
+  ok: boolean; detail: string; taskId?: number; runIds?: number[];
+}> {
+  const pr = (await db.select().from(agentRuns).where(eq(agentRuns.id, parentRunId)).limit(1))[0];
+  if (!pr) return { ok: false, detail: 'parent run not found' };
+  const pt = (await db.select().from(tasks).where(eq(tasks.id, pr.taskId)).limit(1))[0];
+  if (!pt) return { ok: false, detail: 'parent task not found' };
+  // 폭주 가드 — 한 부모가 만들 수 있는 하위 태스크 상한
+  const siblings = await db.select().from(tasks).where(eq(tasks.parentRunId, parentRunId));
+  if (siblings.length >= 8) return { ok: false, detail: 'subtask limit reached (8 per run)' };
+  const n = Math.max(1, Math.min(4, count || 1));
+  const tIns = await db.insert(tasks).values({
+    repoId: pt.repoId, title: title.slice(0, 140), prompt, parentRunId,
+  }).returning();
+  const task = tIns[0]!;
+  const runIds: number[] = [];
+  for (let i = 0; i < n; i++) {
+    const rIns = await db.insert(agentRuns).values({
+      taskId: task.id, machineId: pr.machineId, agent: pr.agent, model: pr.model, status: 'pending',
+    }).returning();
+    const run = rIns[0]!;
+    broadcast({ type: 'run', runId: run.id, taskId: task.id, status: 'pending', agent: run.agent, branch: '', filesChanged: 0 });
+    void launchRun(run.id, real);
+    runIds.push(run.id);
+  }
+  await recordEvent(parentRunId, 'meta', JSON.stringify({ subtask: task.id, title: task.title, runs: runIds }));
+  return { ok: true, detail: `spawned task #${task.id} (${runIds.length} run(s))`, taskId: task.id, runIds };
+}
+
+/** 부모 run 이 발사한 서브태스크 현황 — 에이전트 폴링용. */
+export async function listSubtasks(parentRunId: number): Promise<Array<{
+  id: number; title: string; runs: Array<{ id: number; status: string; filesChanged: number; exitSummary: string }>;
+}>> {
+  const ts = await db.select().from(tasks).where(eq(tasks.parentRunId, parentRunId));
+  const out = [];
+  for (const t of ts) {
+    const rs = await db.select().from(agentRuns).where(eq(agentRuns.taskId, t.id));
+    out.push({
+      id: t.id, title: t.title,
+      runs: rs.map((r) => ({ id: r.id, status: r.status, filesChanged: r.filesChanged, exitSummary: r.exitSummary.slice(0, 200) })),
+    });
+  }
+  return out;
+}
+
 /**
  * 원격 에이전트 kill 스크립트 — pid 파일 기준.
  * $$ 가 그룹 리더가 아닐 수 있어 ps 로 실제 pgid 를 조회해 그룹째 죽인다
@@ -69,6 +198,7 @@ interface RunContext {
   prompt: string;
   real: boolean;
   agent: string;
+  model: string;
 }
 
 async function loadContext(runId: number): Promise<RunContext | null> {
@@ -108,6 +238,7 @@ async function loadContext(runId: number): Promise<RunContext | null> {
     prompt,
     real: config.agent.real,
     agent: run.agent,
+    model: run.model,
   };
 }
 
@@ -155,8 +286,29 @@ export async function launchRun(runId: number, real?: boolean): Promise<void> {
     const pidPrefix = isRemote ? `printf '%s' "$$" > .coxpit-agent.pid && ` : '';
     // 드라이런 모의 스트림은 claude 형태 — 파서도 claude 로 (배관 리허설은 프로바이더 불문)
     const provider = useReal ? getProvider(ctx.agent) : getProvider('claude-code');
-    const cmd = `cd ${shq(wtPath)} && ${pidPrefix}{ ${agentCommand(provider, ctx.prompt, useReal)}; }`;
-    await runAgentChild(runId, ctx.machine, wtPath, cmd, provider);
+    // 셀프 오케스트레이션 — real+로컬 run 에만 토큰/API env 와 능력 고지를 준다
+    // (원격은 127.0.0.1 이 데몬에 닿지 않음). COXPIT_AGENT_ORCH=0 으로 끌 수 있음.
+    let prompt = ctx.prompt;
+    let envPrefix = '';
+    if (useReal && !isRemote && config.agentOrch) {
+      const tok = issueAgentToken(runId);
+      envPrefix = `export COXPIT_API=${shq(`http://127.0.0.1:${config.port}`)} COXPIT_TOKEN=${shq(tok)}; `;
+      prompt += orchestrationNote();
+    }
+    const cmd = `cd ${shq(wtPath)} && ${envPrefix}${pidPrefix}{ ${agentCommand(provider, prompt, useReal, ctx.model)}; }`;
+    // 파일 오케스트레이션 — 로컬 run 이 사는 동안 .coxpit/spawn.json 감시.
+    // .coxpit/ 는 repo exclude 에 넣어 diff/머지를 오염시키지 않는다(멱등).
+    let orchTimer: NodeJS.Timeout | null = null;
+    if (!isRemote && config.agentOrch) {
+      await runShellOn(ctx.machine,
+        `EX=$(git -C ${shq(wtPath)} rev-parse --git-path info/exclude) && { grep -qxF '.coxpit/' "$EX" 2>/dev/null || echo '.coxpit/' >> "$EX"; }`, 8000);
+      orchTimer = startOrchWatch(runId, wtPath, useReal);
+    }
+    try {
+      await runAgentChild(runId, ctx.machine, wtPath, cmd, provider);
+    } finally {
+      if (orchTimer) clearInterval(orchTimer);
+    }
   } catch (e) {
     await recordEvent(runId, 'error', String(e).slice(0, 500));
     await setRun(runId, { status: 'error', endedAt: new Date(), exitSummary: 'orchestrator error' });
@@ -203,9 +355,33 @@ async function runAgentChild(runId: number, machine: MachineTarget, wtPath: stri
   const status = wasStopped ? 'stopped' : code === 0 ? 'done' : 'failed';
   const exitSummary = wasStopped ? 'stopped by user' : lastResult ? lastResult.slice(0, 500) : `exit ${code}`;
   await setRun(runId, { status, endedAt: new Date(), filesChanged, exitSummary });
+  // 문서 산출물을 정착 시점에 스냅샷 — worktree 소멸(머지·Close) 후에도 렌더 뷰 유지. best-effort.
+  if (filesChanged > 0) void snapshotRunDocs(runId);
   void notifySettle(runId, status, filesChanged, exitSummary);
 }
 
+/**
+ * 변경 문서(md/html)를 DB 에 스냅샷. 최신 우선(기존 행 삭제 후 재삽입).
+ * 빈 읽기(worktree 이미 소멸 등)는 기존 스냅샷을 지우지 않는다.
+ */
+export async function snapshotRunDocs(runId: number): Promise<void> {
+  const d = await getRunDocs(runId).catch(() => null);
+  if (!d?.ok || d.docs.length === 0) return;
+  await db.delete(docSnapshots).where(eq(docSnapshots.runId, runId));
+  for (const doc of d.docs) await db.insert(docSnapshots).values({ runId, path: doc.path, kind: doc.kind, content: doc.content });
+}
+
+/** worktree(라이브) → 스냅샷 폴백 공용 로더. server 의 /api/runs/:id/docs·/share 가 사용. */
+export async function loadRunDocs(runId: number): Promise<{
+  docs: Array<{ path: string; kind: string; content: string }>; source: 'worktree' | 'snapshot';
+}> {
+  const live = await getRunDocs(runId).catch(() => null);
+  if (live?.ok && live.docs.length > 0) return { docs: live.docs, source: 'worktree' };
+  const snap = await db.select().from(docSnapshots).where(eq(docSnapshots.runId, runId));
+  if (snap.length > 0) return { docs: snap.map((s) => ({ path: s.path, kind: s.kind, content: s.content })), source: 'snapshot' };
+  return { docs: [], source: 'worktree' };
+}
+
 /** run 정착 웹훅(선택) — COXPIT_WEBHOOK_URL 로 JSON POST. 실패는 무해. */
 async function notifySettle(runId: number, status: string, filesChanged: number, exitSummary: string): Promise<void> {
   if (!config.webhookUrl) return;
@@ -255,9 +431,18 @@ export async function steerRun(runId: number, message: string, mode: 'work' | 'a
   const isRemote = ctx.machine.kind !== 'local' && ctx.machine.address !== '';
   const pidPrefix = isRemote ? `printf '%s' "$$" > .coxpit-agent.pid && ` : '';
   const provider = getProvider(ctx.agent);
-  const resume = provider.resumeCmd(run.sessionId, finalMessage);
-  const cmd = `cd ${shq(wt)} && ${pidPrefix}{ ${resume}; }`;
-  void runAgentChild(runId, ctx.machine, wt, cmd, provider);
+  // steer 세션도 셀프 오케스트레이션 유지(데몬 재시작으로 무효화된 토큰 재발급)
+  const envPrefix = (!isRemote && config.agentOrch)
+    ? `export COXPIT_API=${shq(`http://127.0.0.1:${config.port}`)} COXPIT_TOKEN=${shq(issueAgentToken(runId))}; `
+    : '';
+  const resume = provider.resumeCmd(run.sessionId, finalMessage, run.model || undefined);
+  const cmd = `cd ${shq(wt)} && ${envPrefix}${pidPrefix}{ ${resume}; }`;
+  if (!isRemote && config.agentOrch) {
+    const orchTimer = startOrchWatch(runId, wt, true);
+    void runAgentChild(runId, ctx.machine, wt, cmd, provider).finally(() => clearInterval(orchTimer));
+  } else {
+    void runAgentChild(runId, ctx.machine, wt, cmd, provider);
+  }
   return { ok: true, detail: 'steering' };
 }
 
@@ -748,11 +933,30 @@ export async function reconcileOrphanRuns(): Promise<number> {
   return stale.length;
 }
 
+/**
+ * Close 가드 — 태스크 닫으면 worktree 가 삭제되므로, 아직 살릴 곳 없는 산출물을 경고.
+ * 위험 = 정착(done/failed/stopped) ∧ 변경있음 ∧ 미머지 ∧ export·PR 이벤트 없음.
+ */
+export async function taskCloseRisk(taskId: number): Promise<Array<{ runId: number; filesChanged: number }>> {
+  const trs = await db.select().from(agentRuns).where(eq(agentRuns.taskId, taskId));
+  const atRisk: Array<{ runId: number; filesChanged: number }> = [];
+  for (const r of trs) {
+    if (!['done', 'failed', 'stopped'].includes(r.status)) continue;
+    if (r.filesChanged <= 0) continue;
+    const evs = await db.select().from(agentEvents).where(eq(agentEvents.runId, r.id));
+    if (evs.some((e) => e.kind === 'export' || e.kind === 'pr')) continue; // 산출물이 이미 탈출함
+    atRisk.push({ runId: r.id, filesChanged: r.filesChanged });
+  }
+  return atRisk;
+}
+
 export async function cleanupRun(runId: number): Promise<{ ok: boolean; detail: string }> {
   const ctx = await loadContext(runId);
   const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, runId)).limit(1);
   const run = rr[0];
   if (!ctx || !run || !run.worktreePath) return { ok: false, detail: 'no worktree' };
+  // worktree 를 지우기 전에 문서 스냅샷(정착 안 하는 워크벤치·수정편집도 포착). best-effort.
+  await snapshotRunDocs(runId).catch(() => { /* 스냅샷 실패는 정리를 막지 않음 */ });
   // 원격에 잔존 에이전트가 있으면 worktree 제거 전에 죽인다(파일 잠금·좀비 방지).
   if (ctx.machine.kind !== 'local' && ctx.machine.address !== '') {
     await runShellOn(ctx.machine, remoteKillScript(run.worktreePath), 15000);

package/src/providers.ts

@@ -24,8 +24,9 @@ export interface Provider {
   id: string;
   label: string;
   bin: string;
-  launchCmd(prompt: string): string;
-  resumeCmd(sessionId: string, message: string): string;
+  /** model 비었으면 CLI 기본값 사용(플래그 미첨부). */
+  launchCmd(prompt: string, model?: string): string;
+  resumeCmd(sessionId: string, message: string, model?: string): string;
   /** null = 저장하지 않는 라인(스트림 잡음) */
   parseLine(raw: string): ParsedEvent | null;
 }
@@ -52,13 +53,14 @@ const claudeProvider: Provider = {
   id: 'claude-code',
   label: 'Claude Code',
   get bin() { return config.agent.bin; },
-  launchCmd(prompt: string): string {
+  launchCmd(prompt: string, model?: string): string {
     return `${config.agent.bin} -p ${shq(prompt)} --output-format stream-json --verbose` +
-      ` --permission-mode ${config.agent.perm}`;
+      ` --permission-mode ${config.agent.perm}` + (model ? ` --model ${shq(model)}` : '');
   },
-  resumeCmd(sessionId: string, message: string): string {
+  resumeCmd(sessionId: string, message: string, model?: string): string {
     return `${config.agent.bin} -p --resume ${shq(sessionId)} ${shq(message)}` +
-      ` --output-format stream-json --verbose --permission-mode ${config.agent.perm}`;
+      ` --output-format stream-json --verbose --permission-mode ${config.agent.perm}` +
+      (model ? ` --model ${shq(model)}` : '');
   },
   parseLine(raw: string): ParsedEvent | null {
     const s = raw.trim();
@@ -116,12 +118,14 @@ const codexProvider: Provider = {
   id: 'codex',
   label: 'Codex',
   get bin() { return config.codex.bin; },
-  launchCmd(prompt: string): string {
-    return `${config.codex.bin} exec --json --sandbox ${config.codex.sandbox} ${shq(prompt)}`;
+  launchCmd(prompt: string, model?: string): string {
+    return `${config.codex.bin} exec --json --sandbox ${config.codex.sandbox}` +
+      (model ? ` -m ${shq(model)}` : '') + ` ${shq(prompt)}`;
   },
-  resumeCmd(sessionId: string, message: string): string {
-    // --sandbox 는 exec 의 플래그(resume 서브커맨드는 안 받음) — 반드시 resume 앞에.
-    return `${config.codex.bin} exec --json --sandbox ${config.codex.sandbox} resume ${shq(sessionId)} ${shq(message)}`;
+  resumeCmd(sessionId: string, message: string, model?: string): string {
+    // --sandbox·-m 는 exec 의 플래그(resume 서브커맨드는 안 받음) — 반드시 resume 앞에.
+    return `${config.codex.bin} exec --json --sandbox ${config.codex.sandbox}` +
+      (model ? ` -m ${shq(model)}` : '') + ` resume ${shq(sessionId)} ${shq(message)}`;
   },
   parseLine(raw: string): ParsedEvent | null {
     const s = raw.trim();

package/src/server.ts

@@ -3,16 +3,17 @@ import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolve as presolve, dirname as pdirname, join as pjoin } from 'node:path';
 import { createRequire } from 'node:module';
+import { randomBytes } from 'node:crypto';
 import Fastify, { type FastifyInstance } from 'fastify';
 import websocket from '@fastify/websocket';
 import { eq } from 'drizzle-orm';
 import { authGate } from './auth';
 import { config } from './config';
 import { db } from './db';
-import { machines, repos, tasks, agentRuns, agentEvents, designCaptures } from './db/schema';
+import { machines, repos, tasks, agentRuns, agentEvents, designCaptures, shareLinks } from './db/schema';
 import { BOOKMARKLET_JS } from './design';
 import { runShellOn, shq } from './exec';
-import { launchRun, cleanupRun, stopRun, getRunDiff, getRunDocs, mergeRun, getRunTermInfo, steerRun, exportRun, prRun, integrateRuns, planFanout, reviewTask, syncRun, openWorkbench } from './orchestrator';
+import { launchRun, cleanupRun, stopRun, getRunDiff, loadRunDocs, mergeRun, getRunTermInfo, steerRun, exportRun, prRun, integrateRuns, planFanout, reviewTask, syncRun, openWorkbench, spawnSubtasks, listSubtasks, resolveAgentToken, taskCloseRisk } from './orchestrator';
 import { openTerm } from './term';
 import { addSink, removeSink, broadcast } from './hub';
 import { getProvider, listProviders } from './providers';
@@ -28,6 +29,135 @@ const VENDOR: Record<string, { pkg: string; rel: string; type: string }> = {
   'addon-unicode11.js': { pkg: '@xterm/addon-unicode11/package.json', rel: 'lib/addon-unicode11.js', type: 'text/javascript' },
 };
 
+// ─── 읽기 전용 공유 페이지 (서버 렌더 스냅샷 — 스크립트 0, 액션 0) ───────────
+const escH = (x: unknown): string =>
+  String(x ?? '').replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]!));
+
+/** 경량 마크다운 → HTML (보드 mdLite 의 서버측 판, 동일 문법). 입력은 먼저 escH. */
+function mdLiteHTML(src: string): string {
+  let s = escH(src);
+  s = s.replace(/```[a-z]*\n([\s\S]*?)```/g, (_m, c: string) =>
+    '<pre style="background:#0e1118;border:1px solid #222835;border-radius:7px;padding:8px 10px;overflow-x:auto">' + c + '</pre>');
+  s = s.replace(/^### (.+)$/gm, '<h3>$1</h3>');
+  s = s.replace(/^## (.+)$/gm, '<h2>$1</h2>');
+  s = s.replace(/^# (.+)$/gm, '<h2>$1</h2>');
+  s = s.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  s = s.replace(/`([^`]+)`/g, '<code>$1</code>');
+  s = s.replace(/^[-*] (.+)$/gm, '<li>$1</li>');
+  s = s.replace(/(<li>[\s\S]*?<\/li>)(?!\s*<li>)/g, '<ul>$1</ul>');
+  s = s.split(/\n{2,}/).map((b) => /^<(h2|h3|ul|pre)/.test(b.trim()) ? b : (b.trim() ? '<p>' + b.replace(/\n/g, '<br>') + '</p>' : '')).join('');
+  return s;
+}
+
+/** 공유 페이지 Documents 섹션 — md 는 mdLiteHTML, html 은 sandbox iframe. */
+function shareDocsHTML(docs: Array<{ path: string; kind: string; content: string }>): string {
+  if (!docs.length) return '';
+  const body = docs.map((d) => d.kind === 'md'
+    ? `<div class="doc"><div class="doc-h">${escH(d.path)}</div><div class="doc-b">${mdLiteHTML(d.content)}</div></div>`
+    : `<div class="doc"><div class="doc-h">${escH(d.path)}</div><iframe sandbox="" class="doc-frame" srcdoc="${escH(d.content)}"></iframe></div>`).join('');
+  return `<div class="sec">Documents</div>${body}`;
+}
+
+/** 보드 humanize 의 서버측 축약판 — 이벤트 한 줄을 {k, t} 로. null = 잡음. */
+function shareLine(kind: string, payload: string): { k: string; t: string } | null {
+  if (kind === 'steer') return { k: 'steer', t: '→ ' + payload };
+  if (kind === 'ask') return { k: 'ask', t: '? ' + payload };
+  if (kind === 'sync' || kind === 'pr' || kind === 'export') return { k: kind, t: payload };
+  if (kind === 'stderr' || kind === 'error') return { k: kind, t: payload };
+  try {
+    const o = JSON.parse(payload) as {
+      type?: string; subtype?: string; text?: string; result?: string; worktree?: string;
+      message?: { content?: Array<{ type?: string; text?: string; name?: string; input?: Record<string, string> }> };
+    };
+    if (o.type === 'system') return o.subtype === 'init' || !o.subtype ? { k: 'session', t: 'started' } : null;
+    if (o.type === 'user') return null;
+    if (o.type === 'assistant' && o.message) {
+      const parts: string[] = [];
+      for (const c of o.message.content ?? []) {
+        if (c.type === 'text' && c.text) parts.push(c.text);
+        else if (c.type === 'tool_use') {
+          const i = c.input ?? {};
+          const arg = i.file_path || i.command || i.path || i.pattern || '';
+          parts.push('▸ ' + (c.name ?? 'tool') + (arg ? ' — ' + String(arg).split('/').slice(-2).join('/').slice(0, 60) : ''));
+        }
+      }
+      return parts.length ? { k: 'agent', t: parts.join(' · ') } : null;
+    }
+    if (o.type === 'assistant' && o.text) return { k: 'said', t: o.text };
+    if (o.type === 'result') return { k: 'done', t: o.result || 'finished' };
+    if (kind === 'meta' && o.worktree) return { k: 'start', t: 'worktree ' + String(o.worktree).split('/').slice(-2).join('/') };
+    return null;
+  } catch { return payload.trim().startsWith('{') ? null : { k: kind, t: payload.slice(0, 160) }; }
+}
+
+function shareDiffHTML(text: string): string {
+  if (!text.trim()) return '<span style="color:#5c6675">no changes</span>';
+  return text.slice(0, 120_000).split('\n').map((l) => {
+    const e = escH(l);
+    if (l.startsWith('diff --git') || l.startsWith('+++') || l.startsWith('---')) return `<span class="f">${e}</span>`;
+    if (l.startsWith('@@')) return `<span class="h">${e}</span>`;
+    if (l.startsWith('+')) return `<span class="a">${e}</span>`;
+    if (l.startsWith('-')) return `<span class="d">${e}</span>`;
+    return e;
+  }).join('\n');
+}
+
+function sharePageHTML(
+  run: { id: number; status: string; branch: string; agent: string; filesChanged: number; exitSummary: string },
+  taskTitle: string,
+  events: Array<{ kind: string; payload: string }>,
+  diff: string,
+  docs: Array<{ path: string; kind: string; content: string }> = [],
+): string {
+  const lines = events.map((e) => shareLine(e.kind, e.payload)).filter((x): x is { k: string; t: string } => !!x);
+  const sc: Record<string, string> = { done: '#3fb970', merged: '#4ec9b0', failed: '#e5534b', error: '#e5534b', stopped: '#a371f7', running: '#4184e4', open: '#4ec9b0' };
+  const color = sc[run.status] ?? '#8792a2';
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>coxpit · r${run.id} — ${escH(taskTitle)}</title>
+<style>
+  body{margin:0;background:#0b0d12;color:#dee4ec;font-family:-apple-system,'Segoe UI',sans-serif;font-size:14px;line-height:1.55}
+  .wrap{max-width:960px;margin:0 auto;padding:28px 18px 60px}
+  .hd{display:flex;align-items:baseline;gap:10px;flex-wrap:wrap;margin-bottom:4px}
+  .mark{color:#4ec9b0;font-family:ui-monospace,monospace;font-weight:700}
+  .rid{color:#5c6675;font-family:ui-monospace,monospace}
+  h1{font-size:17px;margin:6px 0 2px}
+  .chip{display:inline-block;font-family:ui-monospace,monospace;font-size:11px;text-transform:uppercase;letter-spacing:.08em;
+    padding:2px 10px;border:1px solid ${color};border-radius:999px;color:${color}}
+  .meta{color:#5c6675;font-family:ui-monospace,monospace;font-size:11.5px;margin:8px 0 22px}
+  .sec{font-family:ui-monospace,monospace;font-size:10px;text-transform:uppercase;letter-spacing:.14em;color:#5c6675;
+    border-bottom:1px solid #222835;padding-bottom:6px;margin:26px 0 10px}
+  .tl{font-family:ui-monospace,monospace;font-size:12px;display:flex;flex-direction:column;gap:6px}
+  .tl .k{color:#4ec9b0;display:inline-block;min-width:64px}
+  .tl .t{color:#8792a2;word-break:break-word}
+  pre{background:#0e1118;border:1px solid #222835;border-radius:10px;padding:14px;overflow-x:auto;
+    font-family:ui-monospace,monospace;font-size:11.5px;line-height:1.5;white-space:pre-wrap;word-break:break-all}
+  .f{color:#4ec9b0;font-weight:600}.h{color:#4184e4}.a{color:#3fb970}.d{color:#e5534b}
+  .sum{background:#12151c;border:1px solid #222835;border-radius:10px;padding:12px 14px;color:#8792a2;font-size:13px}
+  .doc{margin-bottom:18px}
+  .doc-h{font-family:ui-monospace,monospace;font-size:10.5px;color:#4ec9b0;border-bottom:1px solid #222835;padding-bottom:5px;margin-bottom:8px;word-break:break-all}
+  .doc-b{font-size:13.5px;line-height:1.65;color:#8792a2}
+  .doc-b h1,.doc-b h2{font-size:15px;color:#dee4ec;margin:12px 0 6px}
+  .doc-b h3{font-size:13px;color:#dee4ec;margin:10px 0 4px}
+  .doc-b ul{margin:4px 0 8px;padding-left:18px}.doc-b li{margin-bottom:3px}
+  .doc-b strong{color:#dee4ec}.doc-b p{margin:0 0 8px}
+  .doc-b code{font-family:ui-monospace,monospace;font-size:.9em;background:#0e1118;padding:1px 5px;border-radius:4px;color:#4ec9b0}
+  .doc-frame{width:100%;height:420px;border:1px solid #222835;border-radius:8px;background:#fff}
+  .ft{margin-top:40px;color:#3d4657;font-size:12px;font-family:ui-monospace,monospace}
+  .ft a{color:#4ec9b0;text-decoration:none}
+</style></head><body><div class="wrap">
+  <div class="hd"><span class="mark">coxpit</span><span class="rid">r${run.id}</span><span class="chip">${escH(run.status)}</span></div>
+  <h1>${escH(taskTitle)}</h1>
+  <div class="meta">branch ${escH(run.branch || '—')} · ${run.filesChanged} file(s) changed · agent ${escH(run.agent)}</div>
+  ${run.exitSummary ? `<div class="sum">${escH(run.exitSummary)}</div>` : ''}
+  ${shareDocsHTML(docs)}
+  <div class="sec">Timeline</div>
+  <div class="tl">${lines.map((l) => `<div><span class="k">${escH(l.k)}</span><span class="t">${escH(l.t.slice(0, 220))}</span></div>`).join('') || '<span style="color:#5c6675">no events</span>'}</div>
+  <div class="sec">Diff</div>
+  <pre>${shareDiffHTML(diff)}</pre>
+  <div class="ft">read-only snapshot shared via <a href="https://github.com/hanmariyang/coxpit-oss">coxpit</a></div>
+</div></body></html>`;
+}
+
 export async function buildServer(): Promise<FastifyInstance> {
   const app = Fastify({ logger: true });
   await app.register(websocket);
@@ -210,6 +340,26 @@ export async function buildServer(): Promise<FastifyInstance> {
     return { ok: true };
   });
 
+  // 기본 브랜치 변경 — merge·Sync base·PR 이 향할 대상. develop-flow repo 대응.
+  app.patch('/api/repos/:id', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    const b = (req.body ?? {}) as { defaultBranch?: string };
+    const branch = (b.defaultBranch ?? '').trim();
+    if (!/^[\w.\-/]{1,80}$/.test(branch)) return reply.code(400).send({ error: 'invalid branch name' });
+    const rp = await db.select().from(repos).where(eq(repos.id, id)).limit(1);
+    const repo = rp[0];
+    if (!repo) return reply.code(404).send({ error: 'not found' });
+    const mr = await db.select().from(machines).where(eq(machines.id, repo.machineId)).limit(1);
+    const m = mr[0];
+    if (!m) return reply.code(404).send({ error: 'machine not found' });
+    // branch 는 charset 가드 통과(셸 메타문자 없음). 전체 ref 를 인용해 전달.
+    const check = await runShellOn(m,
+      `git -C ${shq(repo.path)} rev-parse --verify --quiet ${shq('refs/heads/' + branch)} >/dev/null && echo OK`, 10000);
+    if (!check.stdout.includes('OK')) return reply.code(400).send({ error: `branch '${branch}' not found in the repository` });
+    await db.update(repos).set({ defaultBranch: branch }).where(eq(repos.id, id));
+    return { ok: true, defaultBranch: branch };
+  });
+
   // 디렉토리 브라우저 — repo 등록용 파일 피커(로컬 머신 전용, 인증 게이트 뒤).
   app.get('/api/browse', async (req) => {
     const q = (req.query ?? {}) as { path?: string };
@@ -311,7 +461,7 @@ export async function buildServer(): Promise<FastifyInstance> {
   // N개의 에이전트 run 을 만들고 각자 오케스트레이션 시작(fire-and-forget).
   app.post('/api/tasks/:id/run', async (req, reply) => {
     const id = Number((req.params as { id: string }).id);
-    const b = (req.body ?? {}) as { agent?: string; count?: number; real?: boolean };
+    const b = (req.body ?? {}) as { agent?: string; count?: number; real?: boolean; model?: string };
     const tr = await db.select().from(tasks).where(eq(tasks.id, id)).limit(1);
     const task = tr[0];
     if (!task) return reply.code(404).send({ error: 'task not found' });
@@ -321,10 +471,15 @@ export async function buildServer(): Promise<FastifyInstance> {
     const count = Math.max(1, Math.min(8, Number(b.count) || 1));
     // 미지의 값은 기본 프로바이더로 정규화(런처 조작·API 오타 방어)
     const agent = getProvider(b.agent).id;
+    // 모델 지정(선택) — 셸 안전 문자만, 빈값 = CLI 기본
+    const model = (b.model ?? '').trim();
+    if (model && (model.length > 64 || !/^[\w.\-:/]*$/.test(model))) {
+      return reply.code(400).send({ error: 'invalid model name' });
+    }
     const created: Array<typeof agentRuns.$inferSelect> = [];
     for (let i = 0; i < count; i++) {
       const ins = await db.insert(agentRuns)
-        .values({ taskId: id, machineId: rp[0].machineId, agent, status: 'pending' })
+        .values({ taskId: id, machineId: rp[0].machineId, agent, model, status: 'pending' })
         .returning();
       created.push(ins[0]!);
     }
@@ -364,8 +519,14 @@ export async function buildServer(): Promise<FastifyInstance> {
   // 태스크 닫기 — 살아있는 run 중지 후 소속 run 전체 worktree/브랜치 정리.
   app.post('/api/tasks/:id/close', async (req, reply) => {
     const id = Number((req.params as { id: string }).id);
+    const b = (req.body ?? {}) as { force?: boolean };
     const tr = await db.select().from(tasks).where(eq(tasks.id, id)).limit(1);
     if (!tr[0]) return reply.code(404).send({ error: 'task not found' });
+    // Close 가드 — 아직 살릴 곳 없는 산출물(미머지·미export·무PR)이 있으면 확인 요구.
+    if (!b.force) {
+      const atRisk = await taskCloseRisk(id);
+      if (atRisk.length) return reply.code(409).send({ error: 'unmerged output', atRisk });
+    }
     const trs = await db.select().from(agentRuns).where(eq(agentRuns.taskId, id));
 
     let anyStopped = false;
@@ -509,12 +670,99 @@ export async function buildServer(): Promise<FastifyInstance> {
     return getRunDiff(id);
   });
 
-  // Doc 모드 — 변경된 문서(md/html)를 내용째 (렌더 비교용, 읽기 전용)
+  // Doc 모드 — 변경된 문서(md/html) 내용째 (렌더 뷰). worktree 라이브 → 스냅샷 폴백.
   app.get('/api/runs/:id/docs', async (req, reply) => {
     const id = Number((req.params as { id: string }).id);
     const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, id)).limit(1);
     if (!rr[0]) return reply.code(404).send({ error: 'not found' });
-    return getRunDocs(id);
+    const { docs, source } = await loadRunDocs(id);
+    return { ok: true, docs, source };
+  });
+
+  // ─── 에이전트 셀프 오케스트레이션 (run 별 Bearer 토큰 — authGate 예외, 여기서 자체 검증) ──
+  const agentAuth = (req: { headers: { authorization?: string } }): number | null => {
+    const h = req.headers.authorization ?? '';
+    if (!h.startsWith('Bearer ')) return null;
+    return resolveAgentToken(h.slice(7).trim());
+  };
+
+  app.post('/api/agent/subtasks', async (req, reply) => {
+    const rid = agentAuth(req);
+    if (rid == null) return reply.code(401).send({ error: 'invalid agent token' });
+    const b = (req.body ?? {}) as { title?: string; prompt?: string; count?: number };
+    if (!b.title?.trim() || !b.prompt?.trim()) return reply.code(400).send({ error: 'title and prompt required' });
+    const r = await spawnSubtasks(rid, b.title.trim(), b.prompt, Number(b.count) || 1);
+    if (!r.ok) return reply.code(409).send({ error: r.detail });
+    return reply.code(201).send(r);
+  });
+
+  app.get('/api/agent/subtasks', async (req, reply) => {
+    const rid = agentAuth(req);
+    if (rid == null) return reply.code(401).send({ error: 'invalid agent token' });
+    return { subtasks: await listSubtasks(rid) };
+  });
+
+  // ─── GitHub 이슈/PR → 태스크 초안 (자동 발사 아님 — 사람이 검토 후 Run fleet) ──
+  app.post('/api/tasks/from-github', async (req, reply) => {
+    const b = (req.body ?? {}) as { url?: string };
+    const m = (b.url ?? '').trim().match(/^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/(issues|pull)\/(\d+)/);
+    if (!m) return reply.code(400).send({ error: 'expected a github.com issue or pull request URL' });
+    const [, owner, repo, kind, num] = m as unknown as [string, string, string, 'issues' | 'pull', string];
+    const isPr = kind === 'pull';
+    let title = '', body = '';
+    // gh CLI 우선(사설 repo 는 gh 인증이 필요) — 없거나 실패하면 공개 API 폴백
+    const local = { slug: 'local', kind: 'local', address: '', sshUser: '' };
+    const ghCmd = `gh ${isPr ? 'pr' : 'issue'} view ${shq(b.url!.trim())} --json title,body`;
+    const g = await runShellOn(local, `command -v gh >/dev/null 2>&1 && ${ghCmd}`, 20000);
+    if (g.ok) {
+      try { const j = JSON.parse(g.stdout) as { title?: string; body?: string }; title = j.title ?? ''; body = j.body ?? ''; } catch { /* fall through */ }
+    }
+    if (!title) {
+      try {
+        const r = await fetch(`https://api.github.com/repos/${owner}/${repo}/issues/${num}`, {
+          headers: { 'user-agent': 'coxpit', accept: 'application/vnd.github+json' },
+          signal: AbortSignal.timeout(10000),
+        });
+        if (r.ok) { const j = await r.json() as { title?: string; body?: string }; title = j.title ?? ''; body = j.body ?? ''; }
+      } catch { /* unreachable/private */ }
+    }
+    if (!title) return reply.code(502).send({ error: 'could not fetch it — private repo needs the gh CLI signed in on the daemon machine' });
+    return {
+      ok: true,
+      title: `${repo}#${num} · ${title}`.slice(0, 140),
+      prompt: `GitHub ${isPr ? 'pull request' : 'issue'}: ${b.url!.trim()}\n\n# ${title}\n\n${(body || '(no description)').slice(0, 6000)}\n\n---\nWork in this repository to address the ${isPr ? 'pull request' : 'issue'} above. Keep the change minimal and verifiable, and say how to verify it in your final summary.`,
+    };
+  });
+
+  // ─── 읽기 전용 공유 링크 — 토큰 URL 이 곧 능력(스냅샷 뷰, 액션 없음) ──
+  app.post('/api/runs/:id/share', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, id)).limit(1);
+    if (!rr[0]) return reply.code(404).send({ error: 'not found' });
+    const ex = await db.select().from(shareLinks).where(eq(shareLinks.runId, id));
+    if (ex[0]) return { ok: true, url: `/share/${ex[0].token}`, existing: true };
+    const token = randomBytes(12).toString('base64url');
+    await db.insert(shareLinks).values({ runId: id, token });
+    return reply.code(201).send({ ok: true, url: `/share/${token}` });
+  });
+
+  app.delete('/api/runs/:id/share', async (req, reply) => {
+    const id = Number((req.params as { id: string }).id);
+    await db.delete(shareLinks).where(eq(shareLinks.runId, id));
+    return { ok: true };
+  });
+
+  app.get('/share/:token', async (req, reply) => {
+    const { token } = req.params as { token: string };
+    const sl = (await db.select().from(shareLinks).where(eq(shareLinks.token, token)).limit(1))[0];
+    if (!sl) return reply.code(404).type('text/html').send('<!doctype html><meta charset="utf-8"><body style="background:#0b0d12;color:#8792a2;font-family:ui-monospace,monospace;padding:40px">share link not found or revoked</body>');
+    const run = (await db.select().from(agentRuns).where(eq(agentRuns.id, sl.runId)).limit(1))[0];
+    if (!run) return reply.code(404).send({ error: 'run gone' });
+    const task = (await db.select().from(tasks).where(eq(tasks.id, run.taskId)).limit(1))[0];
+    const evs = await db.select().from(agentEvents).where(eq(agentEvents.runId, run.id));
+    const d = await getRunDiff(run.id).catch(() => ({ ok: false, diff: '', stat: '' }));
+    const { docs } = await loadRunDocs(run.id);
+    return reply.type('text/html').send(sharePageHTML(run, task?.title ?? `task ${run.taskId}`, evs, d.ok ? d.diff : '', docs));
   });
 
   // 라이브 스트림 좌석 — 오케스트레이터가 run/event 를 여기로 broadcast.