runlist 0.96.0 → 0.97.0

package/assets/app/record-navigation.mjs

@@ -21,58 +21,103 @@ export function nativeContent(record) {
 }
 
 export function recordNavigation({state,$,api,open,showLibrary,checkout,preferences=()=>({records:'pending'}),notice,create=async()=>{}}) {
-  const root=$('records-home');let kind='flags',selected=null,offset=0,sequence=0,timer,filters={q:'',status:'pending',severity:'',scope:''},pending=null;
+  const root=$('records-home'),drafts=new Map();let kind='flags',selected=null,selectedCheckout=null,offset=0,sequence=0,timer,filters={q:'',status:'pending',severity:'',scope:''},pending=null,draft=null,storageError='',storageBlocked=false;
   const title=()=>kind==='flags'?'Flags':'Decisions';
-  const recoveryKey=()=>`runlist:record-action:${checkout()}:${kind}:${selected?.key}`;
+  const recoveryKey=()=>`runlist:record-action:${selectedCheckout}:${kind}:${selected?.key}`;
+  const draftKey=()=>`runlist:record-draft:${selectedCheckout}:${kind}:${selected?.key}`;
+  const formValue=()=>({action:$('record-action').value,note:$('record-note').value,choice:$('record-choice').value});
+  const storageMessage='Draft not stored. Keep this window open and retry.';
+  function draftStatus(){
+    if(!$('record-draft-status'))return;
+    const stale=draft&&draft.revision!==selected.revision;
+    $('record-draft-status').textContent=storageError||(stale?'Record changed since this draft. Check the current record before continuing.':draft?'Draft':'');
+    $('record-draft-status').className=storageError||stale?'inline-note':'muted';
+    $('record-draft-current').hidden=!stale||!!pending||!selected.editable;
+    $('record-draft-discard').hidden=!draft||!!pending;
+  }
+  function retainForm(){
+    if(!selected||pending||!$('record-action-form')||$('record-action-form').hidden)return;
+    draft={...draft,version:1,form:formValue(),revision:draft?.revision??selected.revision,path:selected.path,at:Date.now()};drafts.set(draftKey(),draft);
+    try{if(storageBlocked)throw new Error(storageError);localStorage.setItem(draftKey(),JSON.stringify(draft));storageError='';}catch{storageError=storageMessage;}
+    draftStatus();
+    if(storageError)throw new Error(storageError);
+  }
+  function beforeLeave(){if(state.mode!=='records'||root.hidden)return;if(selected&&!pending&&$('record-action-form')&&!$('record-action-form').hidden&&(draft||$('record-note').value||$('record-choice').value))retainForm();}
+  function restoreForm(form){
+    if(!$('record-action-form')||!form)return;
+    for(const [id,value] of [['record-action',form.action],['record-choice',form.choice]]){const field=$(id);if(field.tagName==='SELECT'&&value&&!Array.from(field.options).some(o=>o.value===value)){const option=new Option(`${value} (unavailable)`,value);field.append(option);}field.value=value??'';}
+    $('record-note').value=form.note??'';updateChoice();
+  }
+  function updateChoice(){const ruled=$('record-action').value==='ruled';$('record-choice-label').hidden=!ruled;$('record-choice').required=ruled;}
+  function changed(){try{retainForm();}catch{}}
+
   const url=key=>{const u=new URL(location.href);u.searchParams.set('view',kind);if(key)u.searchParams.set('record',key);else u.searchParams.delete('record');history.replaceState(null,'',u);};
   const run=fn=>async()=>{try{await fn();}catch(error){notice(error.message,true);}};
   function deactivate(){for(const k of ['flags','decisions'])$('library-'+k).setAttribute('aria-pressed','false');}
   function activate(){state.mode='records';$('empty').hidden=true;$('document').hidden=true;root.hidden=false;for(const k of ['flags','decisions'])$('library-'+k).setAttribute('aria-pressed',String(kind===k));for(const k of ['all','hubs','plans','documents'])$('library-'+k).setAttribute('aria-pressed','false');$('doc-title').textContent=title();}
   function setCounts(counts){for(const k of ['flags','decisions'])$('library-'+k+'-count').textContent=counts[k].toLocaleString();}
   async function counts(){const result=await api('records?kind=flags&status=pending');setCounts(result.counts);}
-  async function show(next,key){await showLibrary();kind=next;selected=null;offset=0;filters={q:'',status:preferences().records??'pending',severity:'',scope:''};activate();url(key);if(key)await detail(key);else await load();}
+  async function show(next,key){beforeLeave();await showLibrary();kind=next;selected=null;offset=0;filters={q:'',status:preferences().records??'pending',severity:'',scope:''};activate();url(key);if(key)await detail(key);else await load();}
+  function clearResults(message,{error,retry}={}){
+    if(!$('record-results'))return;
+    const status=document.createElement('p');status.className='library-no-results';status.textContent=error?`${message}: ${error.message}`:message;status.setAttribute('role',error?'alert':'status');
+    $('record-results').replaceChildren(status);$('record-range').textContent=message;$('record-unavailable').textContent='';
+    $('record-previous').disabled=true;$('record-next').disabled=true;
+    if(retry){const button=document.createElement('button');button.id='record-retry';button.className='quiet';button.textContent='Retry';button.onclick=run(()=>load(false,false));$('record-results').append(button);}
+  }
+  function searchChanged(){clearTimeout(timer);sequence++;clearResults('Loading records…');$('record-results').setAttribute('aria-busy','false');}
   function shell(){root.innerHTML=`<div class="library-heading"><div><h1>${title()}</h1><p>${kind==='flags'?'Findings to triage, with original evidence and a history of what happened.':'Questions and outcomes across plans and registers, connected to their source.'}</p></div><div class="record-heading-actions"><button id="records-new" class="primary">New ${kind==='flags'?'flag':'decision'}</button><button id="records-refresh" class="quiet small">↻ Refresh</button></div></div><div class="record-controls"><label class="sr-only" for="record-search">Search ${title()}</label><input id="record-search" class="search" type="search" placeholder="Search ID, question, source…" value="${esc(filters.q)}"><label>Status<select id="record-status"><option value="pending">Needs attention</option><option value="">All statuses</option>${(kind==='flags'?['open','closed','resolved']:['open','held','ruled','closed','unknown']).map(s=>`<option value="${s}">${s==='closed'&&kind==='flags'?'Rejected':s[0].toUpperCase()+s.slice(1)}</option>`).join('')}</select></label>${kind==='flags'?'<label>Severity<select id="record-severity"><option value="">All severities</option><option>problem</option><option>warn</option><option>info</option></select></label>':''}<label>Plan or hub<select id="record-scope"><option value="">All sources</option></select></label></div><div class="library-pagination"><span id="record-range" role="status">Loading records…</span><button id="record-previous" class="quiet small">← Previous</button><button id="record-next" class="quiet small">Next →</button></div><nav id="record-results" aria-label="${title()} list" aria-busy="true"></nav><p id="record-unavailable" class="muted"></p>`;
     $('record-status').value=filters.status;if(kind==='flags')$('record-severity').value=filters.severity;
-    $('record-search').oninput=()=>{filters.q=$('record-search').value;clearTimeout(timer);timer=setTimeout(()=>{offset=0;run(()=>load(false,false))();},180);};
-    for(const [id,key] of [['record-status','status'],['record-severity','severity'],['record-scope','scope']])if($(id))$(id).onchange=()=>{filters[key]=$(id).value;offset=0;run(()=>load(false,false))();};
+    $('record-search').oninput=()=>{filters.q=$('record-search').value;searchChanged();timer=setTimeout(()=>{offset=0;run(()=>load(false,false))();},180);};
+    for(const [id,key] of [['record-status','status'],['record-severity','severity'],['record-scope','scope']])if($(id))$(id).onchange=()=>{filters[key]=$(id).value;offset=0;searchChanged();run(()=>load(false,false))();};
     $('records-new').onclick=run(()=>create(kind==='flags'?'flag':'decision'));$('records-refresh').onclick=run(()=>load(true,false));$('record-previous').onclick=run(()=>{offset=Math.max(0,offset-50);return load(false,false);});$('record-next').onclick=run(()=>{offset+=50;return load(false,false);});
   }
-  async function load(refresh=false,rebuild=true){if(state.busy)throw new Error('Wait for the current save before navigating.');selected=null;pending=null;if(rebuild)shell();activate();url();const own=++sequence;$('record-results').setAttribute('aria-busy','true');$('record-range').textContent='Loading records…';
+  async function load(refresh=false,rebuild=true){beforeLeave();if(state.busy)throw new Error('Wait for the current save before navigating.');selected=null;pending=null;if(rebuild)shell();activate();url();const own=++sequence;clearResults('Loading records…');$('record-results').setAttribute('aria-busy','true');
     try{const params=new URLSearchParams({kind,...filters,offset:String(offset)});if(refresh)params.set('refresh','1');const result=await api(`records?${params}`);if(own!==sequence||state.mode!=='records'||selected)return;setCounts(result.counts);offset=result.offset;
       $('record-scope').replaceChildren(new Option('All sources',''),...result.scopes.map(s=>new Option(s.title,s.path)));$('record-scope').value=filters.scope;
       $('record-range').textContent=result.total?`${offset+1}–${offset+result.records.length} of ${result.total.toLocaleString()}`:'0 records';$('record-previous').disabled=!offset;$('record-next').disabled=!result.hasMore;
       $('record-results').replaceChildren(...result.records.map(row=>{const b=document.createElement('button');b.className='record-row quiet';b.innerHTML=`<span class="record-row-label"><strong>${esc(row.title||row.id||'Unnamed decision')}</strong><small>${esc(row.path)}${row.line?`:${row.line}`:''}</small></span><span class="record-row-meta"><span class="record-id">${esc(row.id??'No ID')}</span><span class="status-badge">${esc(row.status)}</span>${row.severity?`<span class="severity ${esc(row.severity)}">${esc(row.severity)}</span>`:''}${row.triage==='accepted'?'<small>Accepted</small>':''}</span>`;b.onclick=run(()=>detail(row.key));return b;}));
       if(!result.records.length)$('record-results').innerHTML='<p class="library-no-results">No records match these filters. Choose All statuses or try another search.</p>';
-      $('record-unavailable').textContent=result.unavailable?`${result.unavailable} unavailable sources. Refresh to retry.`:'';notice(`${title()} ready.`);
-    }catch(error){if(own===sequence&&$('record-range'))$('record-range').textContent='Records unavailable · try Refresh';throw error;}finally{if(own===sequence&&$('record-results'))$('record-results').setAttribute('aria-busy','false');}
+      $('record-unavailable').textContent=result.unavailable?`${result.unavailable} unavailable sources. Refresh to retry.`:'';
+    }catch(error){if(own===sequence&&state.mode==='records'&&!selected)clearResults(filters.q?'Search unavailable':'Records unavailable',{error,retry:true});}finally{if(own===sequence&&$('record-results'))$('record-results').setAttribute('aria-busy','false');}
   }
   function connectionHtml(links){return links.length?`<div class="record-connections">${links.map((link,i)=>`<button class="quiet small" data-connection="${i}" title="${esc(link.path)}">${esc(link.title)} <span class="muted">${esc(link.kind==='hub'?'Hub':link.type??'Doc')}</span></button>`).join('')}</div>`:'<p class="muted">No linked documents were found in this library.</p>';}
   function historyHtml(history){return history?.length?`<ol class="record-history">${[...history].reverse().map(h=>`<li><strong>${esc(h.event??h.kind??'Recorded')}</strong> <span class="muted">${esc(h.by?.name??h.by?.label??h.by?.id??'')} · ${esc(h.at??'')}</span><p>${esc(h.note??h.reason??'')}</p></li>`).join('')}</ol>`:'<p class="muted">No later actions have been recorded.</p>';}
-  async function detail(key,{allowBusy=false}={}){if(state.busy&&!allowBusy)throw new Error('Wait for the current save before navigating.');const own=++sequence,wantedKind=kind;clearTimeout(timer);notice('Opening record…');const row=await api(`records?${new URLSearchParams({kind,key})}`);if(own!==sequence||kind!==wantedKind||state.mode!=='records')return;selected=row;pending=null;try{pending=JSON.parse(localStorage.getItem(recoveryKey())??'null');}catch{}activate();url(key);renderDetail();window.scrollTo(0,0);notice(pending?'An interrupted review is retained. Retry its exact request or keep it while reloading the record.':`${title()} record ready.`);}
+  async function detail(key,{allowBusy=false,committed=false}={}){if(!committed)beforeLeave();if(state.busy&&!allowBusy)throw new Error('Wait for the current save before navigating.');const own=++sequence,wantedKind=kind,wantedCheckout=checkout();clearTimeout(timer);const row=await api(`records?${new URLSearchParams({kind,key})}`);if(own!==sequence||kind!==wantedKind||checkout()!==wantedCheckout||state.mode!=='records')return;selected=row;selectedCheckout=wantedCheckout;pending=null;draft=null;storageError='';storageBlocked=false;
+    const unreadable=()=>{storageBlocked=true;storageError='Retained record data could not be read. Keep this window open and check local storage.';};
+    try{pending=JSON.parse(localStorage.getItem(recoveryKey())??'null');if(pending&&(!pending.request||!['native/action','flags/triage','save'].includes(pending.route)||typeof pending.request.operationId!=='string'))throw new Error('Invalid review');}catch{pending=null;unreadable();}
+    try{draft=drafts.get(draftKey())??JSON.parse(localStorage.getItem(draftKey())??'null');if(draft&&(!draft.form||typeof draft.form.note!=='string'||typeof draft.form.action!=='string'||typeof draft.form.choice!=='string'))throw new Error('Invalid draft');}catch{draft=drafts.get(draftKey())??null;unreadable();}
+    activate();url(key);renderDetail();window.scrollTo(0,0);
+  }
   function renderDetail(){const r=selected;
     let content;
     if(r.native)content=nativeContent(r)+`<article class="markdown record-body">${markdownHtml(r.body)}</article><details class="record-structured"><summary>Structured record details</summary><pre>${esc(JSON.stringify(r.data??{},null,2))}</pre></details>`;
     else if(kind==='flags')content=`<div class="record-evidence"><section><h2>Original observation</h2><p class="muted">${esc(r.original.file)}${r.original.line?`:${r.original.line}`:''} · ${esc(r.original.at)}</p><pre>${esc(r.original.quote||'File-level finding; no quote was recorded.')}</pre><p class="muted">${esc(r.original.revisionReason)}</p></section><section><h2>Current evidence <span class="status-badge">${esc(r.current.status)}</span></h2><p class="muted">${r.current.line?`Line ${r.current.line}`:'Location unavailable'}</p><pre>${esc(r.current.quote??'Evidence is unavailable or ambiguous.')}</pre><p class="muted">The original observation stays in the record.</p></section></div><h2>History</h2>${historyHtml(r.history)}`;
     else content=decisionContent(r.body)+`${r.missing?.length?`<p class="inline-note">Record gaps: ${esc(r.missing.join(', '))}. Open the source to fill them in.</p>`:''}${r.blocks?.length?`<h2>Blocking work</h2><ul>${r.blocks.map(b=>`<li>${esc(typeof b==='string'?b:b.text)}${b.doc?` <small class="muted">${esc(b.doc)}:${b.line}</small>`:''}</li>`).join('')}</ul>`:''}${r.peers?.length?`<h2>Related records</h2>${r.peers.map(p=>`<details><summary>${esc(p.id)} · ${esc(p.status)} · ${esc(p.path)}</summary><article class="markdown">${markdownHtml(p.body)}</article></details>`).join('')}`:''}`;
-    root.innerHTML=`<div class="record-back"><button id="records-back" class="quiet small">← ${title()}</button><button id="record-reload" class="quiet small">↻ Reload record</button></div><div class="record-heading"><div class="record-eyebrow">${esc(r.id??'Unnamed decision')} · <span class="status-badge">${esc(r.status)}</span> ${r.severity?`· ${esc(r.severity)}`:''}</div><h1>${esc(r.title)}</h1><p class="muted">${esc(r.path)}${r.line?`:${r.line}`:''}</p></div><section class="record-links"><h2>Connected work</h2>${connectionHtml(r.connections??[])}</section>${content}<section class="record-action"><h2>${kind==='flags'?'Triage this flag':'Record an outcome'}</h2>${r.editable?`<form id="record-action-form"><div class="record-action-fields"><label>${kind==='flags'?'Action':'Disposition'}<select id="record-action">${(kind==='flags'?(r.native&&r.status!=='open'?['reopen']:['accept','reject','resolve']):['held','ruled','closed','open']).map(v=>`<option value="${v}">${v[0].toUpperCase()+v.slice(1)}</option>`).join('')}</select></label><label id="record-choice-label" hidden>Selected answer${r.native&&kind==='decisions'?`<select id="record-choice"><option value="">Choose an existing alternative</option>${(r.data?.options??[]).map(o=>`<option value="${esc(o.id)}">${esc(o.label)}</option>`).join('')}</select>`:'<input id="record-choice" maxlength="4000" placeholder="Which answer was chosen?">'}</label></div><label>Reason<textarea id="record-note" required maxlength="4000" rows="3" placeholder="Why is this the right next step?"></textarea></label><p class="muted">${kind==='flags'?'Accept keeps the flag open. Reject closes it. Resolve records a manual resolution; it does not claim a passing check. Reopen retains earlier history.':'The new outcome is recorded with your identity and date. Previous outcomes and the original record are retained.'}</p><button id="record-review-button" class="primary">Review ${kind==='flags'?'triage':'outcome'}</button></form>`:`<p class="muted">${r.readOnlyReason?esc(r.readOnlyReason):r.native?'Repair the native record diagnostics before recording an action.':kind==='flags'?'This flag has already been closed. Its observation and history are retained.':'This record is read only or has no stable ID. Open its source to inspect or complete it.'}</p>`}<div id="record-review" hidden></div></section>`;
+    root.innerHTML=`<div class="record-back"><button id="records-back" class="quiet small">← ${title()}</button><button id="record-reload" class="quiet small">↻ Reload record</button></div><div class="record-heading"><div class="record-eyebrow">${esc(r.id??'Unnamed decision')} · <span class="status-badge">${esc(r.status)}</span> ${r.severity?`· ${esc(r.severity)}`:''}</div><h1>${esc(r.title)}</h1><p class="muted">${esc(r.path)}${r.line?`:${r.line}`:''}</p></div><section class="record-links"><h2>Connected work</h2>${connectionHtml(r.connections??[])}</section>${content}<section class="record-action"><h2>${kind==='flags'?'Triage this flag':'Record an outcome'}</h2>${r.editable?`<form id="record-action-form"><div class="record-action-fields"><label>${kind==='flags'?'Action':'Disposition'}<select id="record-action">${(kind==='flags'?(r.native&&r.status!=='open'?['reopen']:['accept','reject','resolve']):['held','ruled','closed','open']).map(v=>`<option value="${v}">${v[0].toUpperCase()+v.slice(1)}</option>`).join('')}</select></label><label id="record-choice-label" hidden>Selected answer${r.native&&kind==='decisions'?`<select id="record-choice"><option value="">Choose an existing alternative</option>${(r.data?.options??[]).map(o=>`<option value="${esc(o.id)}">${esc(o.label)}</option>`).join('')}</select>`:'<input id="record-choice" maxlength="4000" placeholder="Which answer was chosen?">'}</label></div><label>Reason<textarea id="record-note" required maxlength="4000" rows="3" placeholder="Why is this the right next step?"></textarea></label><button id="record-review-button" class="primary">Review ${kind==='flags'?'triage':'outcome'}</button></form>`:`<p class="muted">${r.readOnlyReason?esc(r.readOnlyReason):r.native?'Repair the native record diagnostics before recording an action.':kind==='flags'?'This flag has already been closed. Its observation and history are retained.':'This record is read only or has no stable ID. Open its source to inspect or complete it.'}</p>`}<p id="record-draft-status" class="muted" role="status"></p><div class="record-review-actions"><button id="record-draft-current" class="quiet small" hidden>Use current record</button><button id="record-draft-discard" class="quiet small" hidden>Discard draft</button></div><div id="record-review" hidden></div></section>`;
     $('records-back').onclick=run(()=>load());$('record-reload').onclick=run(async()=>{await api(`records?kind=${kind}&refresh=1`);await detail(r.key);});
-    for(const b of root.querySelectorAll('[data-connection]'))b.onclick=run(()=>open(r.connections[Number(b.dataset.connection)].path));
-    if(r.editable){$('record-action').onchange=()=>{const ruled=$('record-action').value==='ruled';$('record-choice-label').hidden=!ruled;$('record-choice').required=ruled;};$('record-action-form').onsubmit=e=>{e.preventDefault();run(review)();};}
-    if(pending)renderReview();
+    for(const b of root.querySelectorAll('[data-connection]'))b.onclick=run(()=>{beforeLeave();return open(r.connections[Number(b.dataset.connection)].path);});
+    if(r.editable){$('record-action').onchange=()=>{updateChoice();changed();};for(const id of ['record-note','record-choice']){$(id).oninput=changed;$(id).onchange=changed;}$('record-action-form').onsubmit=e=>{e.preventDefault();return run(review)();};restoreForm(draft?.form);}
+    else if(draft){const retained=document.createElement('pre');retained.className='record-body';retained.textContent=`Draft · ${draft.form.action}${draft.form.choice?` · ${draft.form.choice}`:''}\n${draft.form.note}`;$('record-draft-status').before(retained);}
+    $('record-draft-current').onclick=run(async()=>{if(storageBlocked)throw new Error(storageError);draft.revision=selected.revision;retainForm();});
+    $('record-draft-discard').onclick=run(async()=>{if(storageBlocked)throw new Error(storageError);try{localStorage.removeItem(draftKey());}catch{throw new Error('Draft could not be discarded. Try again.');}drafts.delete(draftKey());draft=null;storageError='';renderDetail();});
+    draftStatus();if(pending)renderReview();
   }
-  async function review(){if(state.busy)return;const action=$('record-action').value,note=$('record-note').value,choice=$('record-choice').value;
-    if(selected.native){const preview=await api('native/preview',{path:selected.path,expectedRevision:selected.revision,operationId:crypto.randomUUID(),action,note,optionId:choice});pending={form:{action,note,choice},route:'native/action',request:preview.request,before:preview.before,label:`Record ${action}`,note};}
-    else if(kind==='flags')pending={form:{action,note,choice},route:'flags/triage',request:{key:selected.key,action,note,expectedRevision:selected.revision,operationId:crypto.randomUUID()},label:`${action[0].toUpperCase()+action.slice(1)} ${selected.id}`,note};
-    else {const preview=await api('decisions/preview',{key:selected.key,expectedRevision:selected.revision,disposition:action,note,choice});pending={form:{action,note,choice},route:'save',request:{path:preview.path,source:preview.source,expectedRevision:preview.expectedRevision,operationId:crypto.randomUUID()},before:preview.before,label:`Record ${action} for ${selected.id}`,note};}
+  async function review(){if(state.busy)return;if(selectedCheckout!==checkout())throw new Error('Open this record in its original checkout.');if(storageBlocked)throw new Error(storageError);retainForm();if(draft.revision!==selected.revision)throw new Error('Check the changed record, then choose Use current record.');const allowed=kind==='flags'?(selected.native&&selected.status!=='open'?['reopen']:['accept','reject','resolve']):['held','ruled','closed','open'];if(!allowed.includes($('record-action').value))throw new Error('Choose an available action.');if(selected.native&&$('record-action').value==='ruled'&&!(selected.data?.options??[]).some(o=>o.id===$('record-choice').value))throw new Error('Choose an available alternative.');const action=$('record-action').value,note=$('record-note').value,choice=$('record-choice').value,own=sequence,wantedCheckout=checkout(),record=selected;let reviewed;
+    if(record.native){const preview=await api('native/preview',{path:record.path,expectedRevision:record.revision,operationId:crypto.randomUUID(),action,note,optionId:choice});reviewed={form:{action,note,choice},route:'native/action',request:preview.request,before:preview.before,label:`Record ${action}`,note};}
+    else if(kind==='flags')reviewed={form:{action,note,choice},route:'flags/triage',request:{key:record.key,action,note,expectedRevision:record.revision,operationId:crypto.randomUUID()},label:`${action[0].toUpperCase()+action.slice(1)} ${record.id}`,note};
+    else {const preview=await api('decisions/preview',{key:record.key,expectedRevision:record.revision,disposition:action,note,choice});reviewed={form:{action,note,choice},route:'save',request:{path:preview.path,source:preview.source,expectedRevision:preview.expectedRevision,operationId:crypto.randomUUID()},before:preview.before,label:`Record ${action} for ${record.id}`,note};}
     // Retain exactly the reviewed request before any write, including its UUID.
-    try{localStorage.setItem(recoveryKey(),JSON.stringify(pending));}catch{pending=null;throw new Error('The review could not be retained in local editor storage. Free some storage and try again.');}renderReview();
+    if(own!==sequence||wantedCheckout!==checkout()||state.mode!=='records')return;pending={...reviewed,path:record.path,at:Date.now()};
+    try{localStorage.setItem(recoveryKey(),JSON.stringify(pending));}catch{pending=null;storageError='Review not stored. Keep this window open and retry.';draftStatus();throw new Error(storageError);}renderReview();
   }
-  function renderReview(){if($('record-action-form'))$('record-action-form').hidden=true;$('record-review').hidden=false;$('record-review').innerHTML=`<h3>${esc(pending.label)}</h3><p>${esc(pending.note)}</p>${pending.before?`<div class="diff">${diffHtml(pending.before,pending.request.source)}</div>`:'<p class="muted">This appends a dated action to the flag history. The original evidence is retained.</p>'}<div class="record-review-actions"><button id="record-confirm" class="primary">Confirm ${kind==='flags'?'triage':'outcome'}</button><button id="record-change" class="quiet">Back to form</button></div><p id="record-action-feedback" role="status"></p>`;$('record-confirm').onclick=run(confirm);$('record-change').onclick=()=>{localStorage.removeItem(recoveryKey());const form=pending.form;pending=null;$('record-review').hidden=true;if($('record-action-form')){$('record-action-form').hidden=false;if(form){$('record-action').value=form.action;$('record-note').value=form.note;$('record-choice').value=form.choice;$('record-action').onchange();}}};}
-  async function confirm(){if(state.busy)return;state.busy=true;$('record-confirm').disabled=true;$('record-change').disabled=true;
-    try{await api(pending.route,pending.request);localStorage.removeItem(recoveryKey());pending=null;await counts();await detail(selected.key,{allowBusy:true});notice('Saved. The source and history are available through the CLI.');}
-    catch(error){if($('record-action-feedback'))$('record-action-feedback').textContent=`${error.message} Your reviewed request is retained. Reload the record to inspect it, or retry this exact request.`;throw error;}
+  function renderReview(){draftStatus();if($('record-action-form'))$('record-action-form').hidden=true;$('record-review').hidden=false;$('record-review').innerHTML=`<h3>${esc(pending.label)}</h3><p>${esc(pending.note)}</p>${pending.before?`<div class="diff">${diffHtml(pending.before,pending.request.source)}</div>`:''}<div class="record-review-actions"><button id="record-confirm" class="primary">Confirm ${kind==='flags'?'triage':'outcome'}</button><button id="record-change" class="quiet">Back to form</button></div><p id="record-action-feedback" role="status"></p>`;$('record-confirm').onclick=run(confirm);$('record-change').onclick=run(async()=>{const form=pending.form??draft?.form;if(!selected.editable)throw new Error('The record is read only. Keep this reviewed request for inspection.');if(storageBlocked)throw new Error(storageError);const restored={version:1,form,revision:pending.request.expectedRevision??draft?.revision??selected.revision,path:selected.path,at:Date.now()};try{localStorage.setItem(draftKey(),JSON.stringify(restored));localStorage.removeItem(recoveryKey());}catch{throw new Error('The review is retained. Local storage must be available before returning to the form.');}draft=restored;drafts.set(draftKey(),draft);pending=null;$('record-review').hidden=true;$('record-action-form').hidden=false;restoreForm(form);draftStatus();});}
+  async function confirm(){if(state.busy||!pending)return;state.busy=true;$('record-confirm').disabled=true;$('record-change').disabled=true;
+    try{if(selectedCheckout!==checkout())throw new Error('Open this review in its original checkout.');await api(pending.route,pending.request);try{localStorage.removeItem(draftKey());localStorage.removeItem(recoveryKey());}catch{throw new Error('Saved, but retained local data could not be cleared. Retry safely with the same request.');}drafts.delete(draftKey());draft=null;pending=null;try{await detail(selected.key,{allowBusy:true,committed:true});await counts();}catch(error){notice(`Saved; refresh unavailable. ${error.message}`,true);}}
+    catch(error){if($('record-action-feedback'))$('record-action-feedback').textContent=`${error.message} Reviewed request retained; retry when ready.`;throw error;}
     finally{state.busy=false;if($('record-confirm'))$('record-confirm').disabled=false;if($('record-change'))$('record-change').disabled=false;}
   }
   for(const k of ['flags','decisions'])$('library-'+k).onclick=run(()=>show(k));
-  return {show,counts,deactivate};
+  window.addEventListener('beforeunload',event=>{try{beforeLeave();}catch{event.preventDefault();event.returnValue='';}});
+  return {show,counts,deactivate,beforeLeave};
 }

package/assets/app/recovery-center.mjs

@@ -1,29 +1,30 @@
 export function recoveryCenter({$,api,checkout,beforeNavigate,resume,notice}) {
   const dialog=$('recovery-dialog');let rows=[],offset=0,hasMore=false,sequence=0;
   function localItems(){
-    const items=[];let unreadable=0;
+    const items=[],reviewed=new Set();let unreadable=0;
     try { for(let i=0;i<localStorage.length;i++) {
-      const key=localStorage.key(i),prefix=`runlist:recovery:${checkout()}:`,lifecycle=`runlist:lifecycle:${checkout()}:`,record=`runlist:record-action:${checkout()}:`,yardstick=`runlist:yardstick:${checkout()}:`;
-      if(!key.startsWith(prefix)&&!key.startsWith(lifecycle)&&!key.startsWith(record)&&!key.startsWith(yardstick)&&key!==`runlist:create:${checkout()}`)continue;
+      const key=localStorage.key(i),prefix=`runlist:recovery:${checkout()}:`,lifecycle=`runlist:lifecycle:${checkout()}:`,record=`runlist:record-action:${checkout()}:`,recordDraft=`runlist:record-draft:${checkout()}:`,yardstick=`runlist:yardstick:${checkout()}:`;
+      if(!key.startsWith(prefix)&&!key.startsWith(lifecycle)&&!key.startsWith(record)&&!key.startsWith(recordDraft)&&!key.startsWith(yardstick)&&key!==`runlist:create:${checkout()}`)continue;
       try {
         const value=JSON.parse(localStorage.getItem(key));if(!value)continue;
         if(key.startsWith(prefix)&&typeof value.path==='string'&&typeof value.source==='string'&&typeof value.baseSource==='string'&&(value.source!==value.baseSource||value.pending))items.push({kind:'local-draft',path:value.path,location:key,draftId:value.draft?.id,operationId:value.pending?.operationId,at:new Date(value.at).toISOString(),stale:!!value.conflicted,state:value.pending?'interrupted':value.conflicted?'conflict':'draft',available:true});
         else if(key.startsWith(yardstick))items.push({kind:'yardstick',path:value.path,operationId:value.operationId,at:'',available:true,state:value.state??'retained'});
         else if(key.startsWith(lifecycle))items.push({kind:'lifecycle',path:value.path,operationId:value.operationId,at:'',available:true,state:'retained'});
-        else if(key.startsWith(record)){const suffix=key.slice(record.length),colon=suffix.indexOf(':');items.push({kind:'record',recordKind:suffix.slice(0,colon),recordKey:suffix.slice(colon+1),path:value.request?.path??'Flag or decision',at:'',available:true,state:'retained'});}
+        else if(key.startsWith(record)){if(!value.request||!['native/action','flags/triage','save'].includes(value.route)||typeof value.request.operationId!=='string')throw new Error('Invalid review');const suffix=key.slice(record.length),colon=suffix.indexOf(':');reviewed.add(key);items.push({kind:'record',recordKind:suffix.slice(0,colon),recordKey:suffix.slice(colon+1),location:key,path:value.path??value.request.path??value.label??'Flag or decision',operationId:value.request.operationId,at:value.at?new Date(value.at).toISOString():'',available:true,state:'retained'});}
+        else if(key.startsWith(recordDraft)&&value.form&&typeof value.form.note==='string'){const suffix=key.slice(recordDraft.length),colon=suffix.indexOf(':');items.push({kind:'record',reviewLocation:record+suffix,recordKind:suffix.slice(0,colon),recordKey:suffix.slice(colon+1),location:key,path:value.path??'Flag or decision',at:new Date(value.at).toISOString(),available:true,state:'draft'});}
         else if(key===`runlist:create:${checkout()}`&&(value.form?.title||value.form?.body||value.review))items.push({kind:'creation',operationId:value.review?.operationId,path:value.review?.path??`${value.form?.folder??''}/${value.form?.filename??'New document'}`,state:value.review?.state??'draft',at:new Date(value.at).toISOString(),available:true});
       }catch{unreadable++;}
     }
     } catch {unreadable++;}
-    return {items,unreadable};
+    return {items:items.filter(row=>!reviewed.has(row.reviewLocation)),unreadable};
   }
-  const label=row=>row.kind==='git-commit'?`Local Git commit · ${row.state}`:row.kind==='creation'?'New document draft':row.kind==='yardstick'?`Product goal assessment · ${row.state}`:row.kind==='lifecycle'?`Status change · ${row.state}`:row.kind==='record'?'Flag or decision review':row.kind==='operation'?'Interrupted save · inspect outcome':row.operationId||row.pendingOperation?'Interrupted save · draft preserved locally':row.stale?'File changed · compare draft':'Draft preserved locally';
+  const label=row=>row.kind==='git-commit'?`Local Git commit · ${row.state}`:row.kind==='creation'?'New document draft':row.kind==='yardstick'?`Product goal assessment · ${row.state}`:row.kind==='lifecycle'?`Status change · ${row.state}`:row.kind==='record'?`${row.recordKind==='flags'?'Flag':'Decision'} ${row.state==='draft'?'draft':'review'}`:row.kind==='operation'?'Interrupted save · inspect outcome':row.operationId||row.pendingOperation?'Interrupted save · draft preserved locally':row.stale?'File changed · compare draft':'Draft preserved locally';
   function render(){
     const query=$('recovery-filter').value.toLowerCase(),visible=rows.filter(row=>`${row.path} ${label(row)}`.toLowerCase().includes(query));
     $('recovery-items').replaceChildren(...visible.map(row=>{
       const section=document.createElement('section');section.className='recovery-item';
       const info=document.createElement('div'),title=document.createElement('strong'),detail=document.createElement('p'),date=document.createElement('small');title.textContent=row.path;detail.textContent=label(row);date.textContent=row.at?new Date(row.at).toLocaleString():'';info.append(title,detail,date);
-      const button=document.createElement('button');button.className='quiet';button.textContent=!row.available?'File unavailable':row.kind==='creation'?'Resume creation':row.kind==='git-commit'||row.kind==='yardstick'||row.kind==='lifecycle'||row.kind==='operation'?'Inspect operation':row.kind==='record'?'Resume review':'Resume draft';button.disabled=!row.available;
+      const button=document.createElement('button');button.className='quiet';button.textContent=!row.available?'File unavailable':row.kind==='creation'?'Resume creation':row.kind==='git-commit'||row.kind==='yardstick'||row.kind==='lifecycle'||row.kind==='operation'?'Inspect operation':row.kind==='record'&&row.state!=='draft'?'Resume review':'Resume draft';button.disabled=!row.available;
       button.onclick=async()=>{try{dialog.close();await resume(row);}catch(error){notice(error.message,true);}};section.append(info,button);return section;
     }));
     if(!visible.length){const message=document.createElement('p');message.className='library-no-results';message.textContent=query?'No recovery items match this filter.':'No unfinished work in this checkout.';$('recovery-items').append(message);}

package/assets/app/settings.mjs

@@ -1,15 +1,53 @@
 import {desktop} from './transport.mjs';
 import {escapeHtml as esc} from './shared.mjs';
-export function appSettings({$,api,checkout,library,notice}){
- const key=()=>`runlist:preferences:${checkout()}`;
+export function appSettings({$,api,checkout,library}){
+ const key=owner=>`runlist:preferences:${owner}`;
  const defaults={sort:'updated',archived:false,records:'pending'};
- const read=()=>{try{const p=JSON.parse(localStorage.getItem(key())??'{}');return {sort:['updated','title','path'].includes(p.sort)?p.sort:'updated',archived:p.archived===true,records:p.records===''?'':'pending'};}catch{return {...defaults};}};
- async function show(){const info=await api('settings'),tool=await api('semantic/settings'),prefs=read();$('settings-checkout').textContent=info.checkout;$('settings-content').innerHTML=`<section class="settings-section"><h3>${desktop?'This computer':'This browser'}</h3><p class="muted">These preferences stay ${desktop?'in Runlist on this computer':'in this browser'}. They apply when you open this checkout.</p><form id="settings-preferences"><div class="settings-fields"><label>Appearance<select id="settings-theme"><option value="system">System</option><option value="light">Light</option><option value="dark">Dark</option></select></label><label>Default document order<select id="settings-sort"><option value="updated">Recently updated</option><option value="title">Title</option><option value="path">File path</option></select></label><label>Default records view<select id="settings-records"><option value="pending">Needs attention</option><option value="">All statuses</option></select></label><label class="settings-check"><input id="settings-archived" type="checkbox"> Include archived documents by default</label></div><button class="primary">Save preferences</button><span id="settings-feedback" role="status"></span></form></section><section class="settings-section"><h3>Semantic search · experimental</h3><p class="muted">${esc(tool.message)} No gmax dependency is bundled with Runlist. Leave both paths blank to use automatic discovery.</p><form id="settings-semantic"><div class="settings-fields"><label>External Node executable<input id="settings-semantic-node" autocomplete="off" placeholder="Absolute path to node"></label><label>gmax entry file<input id="settings-semantic-entry" autocomplete="off" placeholder="Absolute path to grepmax/dist/bin.js"></label></div><button class="quiet">Save tool paths</button><span id="settings-semantic-feedback" role="status"></span></form></section><section class="settings-section"><h3>Templates</h3><p class="muted">View, customize and review the scaffolds for new documents. Saved templates are repository files and can be shared through Git.</p><button id="settings-templates" class="quiet">Open templates</button></section><section class="settings-section"><h3>Checkout rules</h3><p class="muted">Loaded from ${esc(info.configFile??'built-in defaults')}. Edit repository configuration through the CLI or its source; this view shows the effective rules.</p><dl class="settings-paths"><dt>Document roots</dt><dd>${info.roots.map(p=>`<code>${esc(p)}</code>`).join(' ')}</dd><dt>Excluded folders</dt><dd>${info.exclusions.map(p=>`<code>${esc(p)}</code>`).join(' ')}</dd></dl>${info.statuses.typeOrder.map(type=>`<details class="settings-rules"><summary>${esc(type)} · ${info.statuses.byType[type].length} statuses</summary><div class="settings-table"><table><thead><tr><th>Status</th><th>Context</th><th>Behavior</th></tr></thead><tbody>${info.statuses.byType[type].map(s=>`<tr><td>${esc(s.name)}</td><td>${esc(s.context)}</td><td>${esc([s.startable?'Can start':null,s.terminal?'Terminal':null,s.archive?'Archives':null,s.filed?`Files in ${s.filed}`:null,s.staleDays?`Stale after ${s.staleDays} days`:null].filter(Boolean).join(' · ')||'Ordinary')}</td></tr>`).join('')}</tbody></table></div></details>`).join('')}</section><section class="settings-section"><h3>Where changes live</h3><dl class="settings-paths">${Object.entries(info.sharing).map(([name,value])=>`<dt>${esc(name)}</dt><dd>${esc(value)}</dd>`).join('')}</dl></section>`;
- $('settings-semantic-node').value=tool.nodePath;$('settings-semantic-entry').value=tool.entryPath;
- $('settings-semantic').onsubmit=async event=>{event.preventDefault();try{const saved=await api('semantic/settings',{nodePath:$('settings-semantic-node').value.trim(),entryPath:$('settings-semantic-entry').value.trim()});$('settings-semantic-feedback').textContent=saved.message;}catch(error){$('settings-semantic-feedback').textContent=error.message;}};
- $('settings-theme').value=$('theme-mode').value;$('settings-sort').value=prefs.sort;$('settings-archived').checked=prefs.archived;$('settings-records').value=prefs.records;
- $('settings-preferences').onsubmit=async event=>{event.preventDefault();try{const preferences={sort:$('settings-sort').value,archived:$('settings-archived').checked,records:$('settings-records').value};localStorage.setItem(key(),JSON.stringify(preferences));$('theme-mode').value=$('settings-theme').value;$('theme-mode').dispatchEvent(new Event('change'));await library.preferences(preferences);$('settings-feedback').textContent='Preferences saved.';}catch(error){notice(error.message,true);$('settings-feedback').textContent='Preferences could not be saved.';}};
- $('settings-templates').onclick=()=>{$('settings-dialog').close();$('open-templates').click();};$('settings-dialog').showModal();
+ let sequence=0;
+ function readPreferences(owner){try{const p=JSON.parse(localStorage.getItem(key(owner))??'{}');return {value:{sort:['updated','title','path'].includes(p.sort)?p.sort:'updated',archived:p.archived===true,records:p.records===''?'':'pending'}};}catch(error){return {value:{...defaults},error};}}
+ const read=()=>readPreferences(checkout()).value;
+ const detail=error=>error?.message||'Please try again.';
+ async function show(){
+  const own=++sequence,owner=checkout(),prefs=readPreferences(owner),current=()=>own===sequence&&owner===checkout()&&$('settings-dialog').open;
+  $('settings-checkout').textContent=$('checkout').textContent;
+  $('settings-content').innerHTML=`<section class="settings-section"><h3>Preferences</h3><form id="settings-preferences"><div class="settings-fields"><label>Appearance<select id="settings-theme"><option value="system">System</option><option value="light">Light</option><option value="dark">Dark</option></select></label><label>Default document order<select id="settings-sort"><option value="updated">Recently updated</option><option value="title">Title</option><option value="path">File path</option></select></label><label>Default records view<select id="settings-records"><option value="pending">Needs attention</option><option value="">All statuses</option></select></label><label class="settings-check"><input id="settings-archived" type="checkbox"> Include archived documents by default</label></div><button class="primary">Save preferences</button><p id="settings-feedback" role="status"></p></form></section><section class="settings-section"><h3>Templates</h3><button id="settings-templates" class="quiet">Open templates</button></section><details id="settings-advanced" class="settings-section"><summary>Advanced</summary><p class="muted">Preferences stay ${desktop?'on this computer':'in this browser'} for this checkout.</p><section id="settings-semantic-section" class="settings-section"></section><section id="settings-repository-section" class="settings-section"></section></details>`;
+  const feedback=$('settings-feedback'),form=$('settings-preferences'),save=form.querySelector('button');
+  $('settings-theme').value=$('theme-mode').value;$('settings-sort').value=prefs.value.sort;$('settings-archived').checked=prefs.value.archived;$('settings-records').value=prefs.value.records;
+  if(prefs.error)feedback.textContent=`Saved preferences could not be read: ${detail(prefs.error)} Defaults are shown. Try saving again.`;
+  form.onsubmit=async event=>{
+   event.preventDefault();if(!current()||save.disabled)return;
+   const preferences={sort:$('settings-sort').value,archived:$('settings-archived').checked,records:$('settings-records').value},theme=$('settings-theme').value;
+   save.disabled=true;feedback.textContent='';
+   try{localStorage.setItem(key(owner),JSON.stringify(preferences));}
+   catch(error){feedback.textContent=`Preferences could not be saved: ${detail(error)} Try again.`;save.disabled=false;return;}
+   let appearanceError;
+   try{localStorage.setItem('runlist:appearance',theme);$('theme-mode').value=theme;$('theme-mode').dispatchEvent(new Event('change'));}catch(error){appearanceError=error;}
+   let refreshError;try{await library.preferences(preferences);}catch(error){refreshError=error;}
+   if(current()){
+    feedback.textContent=[appearanceError?`Document preferences saved. Appearance could not be saved: ${detail(appearanceError)} Try again.`:'Preferences saved.',refreshError?`Library could not refresh: ${detail(refreshError)} Use Refresh in the library.`:''].filter(Boolean).join(' ');
+    save.disabled=false;
+   }
+  };
+  $('settings-templates').onclick=()=>{sequence++;$('settings-dialog').close();$('open-templates').click();};
+  $('settings-dialog').showModal();
+  async function optional(sectionId,title,route,render){
+   const section=$(sectionId);section.innerHTML=`<h3>${title}</h3><p role="status">Loading…</p>`;
+   try{const value=await api(route);if(current())render(section,value);}
+   catch(error){if(!current())return;section.innerHTML=`<h3>${title}</h3><p id="${sectionId}-feedback" role="status">Could not load: ${esc(detail(error))}</p><button id="${sectionId}-retry" class="quiet">Retry</button>`;section.querySelector('button').onclick=()=>optional(sectionId,title,route,render);}
+  }
+  const tool=optional('settings-semantic-section','Semantic search · experimental','semantic/settings',(section,tool)=>{
+   section.innerHTML=`<h3>Semantic search · experimental</h3><p class="muted">${esc(tool.message)} Leave paths blank for automatic discovery.</p><form id="settings-semantic"><div class="settings-fields"><label>External Node executable<input id="settings-semantic-node" autocomplete="off" placeholder="Absolute path to node"></label><label>gmax entry file<input id="settings-semantic-entry" autocomplete="off" placeholder="Absolute path to grepmax/dist/bin.js"></label></div><button class="quiet">Save tool paths</button><p id="settings-semantic-feedback" role="status"></p></form>`;
+   const node=$('settings-semantic-node'),entry=$('settings-semantic-entry'),form=$('settings-semantic'),feedback=$('settings-semantic-feedback'),save=form.querySelector('button');node.value=tool.nodePath??'';entry.value=tool.entryPath??'';
+   form.onsubmit=async event=>{event.preventDefault();if(!current()||save.disabled)return;save.disabled=true;feedback.textContent='';try{const saved=await api('semantic/settings',{nodePath:node.value.trim(),entryPath:entry.value.trim()});if(current())feedback.textContent=saved.message;}catch(error){if(current())feedback.textContent=`Tool paths could not be saved: ${detail(error)} Try again.`;}finally{if(current())save.disabled=false;}};
+  });
+  const repository=optional('settings-repository-section','Checkout rules','settings',(section,info)=>{
+   if(info.checkout)$('settings-checkout').textContent=info.checkout;
+   section.innerHTML=`<h3>Checkout rules</h3><p class="muted">${esc(info.configFile??'Built-in defaults')}</p><dl class="settings-paths"><dt>Document roots</dt><dd>${info.roots.map(p=>`<code>${esc(p)}</code>`).join(' ')}</dd><dt>Excluded folders</dt><dd>${info.exclusions.map(p=>`<code>${esc(p)}</code>`).join(' ')}</dd></dl>${info.statuses.typeOrder.map(type=>`<details class="settings-rules"><summary>${esc(type)} · ${info.statuses.byType[type].length} statuses</summary><div class="settings-table"><table><thead><tr><th>Status</th><th>Context</th><th>Behavior</th></tr></thead><tbody>${info.statuses.byType[type].map(s=>`<tr><td>${esc(s.name)}</td><td>${esc(s.context)}</td><td>${esc([s.startable?'Can start':null,s.terminal?'Terminal':null,s.archive?'Archives':null,s.filed?`Files in ${s.filed}`:null,s.staleDays?`Stale after ${s.staleDays} days`:null].filter(Boolean).join(' · ')||'Ordinary')}</td></tr>`).join('')}</tbody></table></div></details>`).join('')}<h3>Where changes live</h3><dl class="settings-paths">${Object.entries(info.sharing).map(([name,value])=>`<dt>${esc(name)}</dt><dd>${esc(value)}</dd>`).join('')}</dl>`;
+  });
+  await Promise.all([tool,repository]);
  }
- $('open-settings').onclick=()=>show().catch(error=>notice(error.message,true));$('settings-close').onclick=()=>$('settings-dialog').close();return {read};
+ $('open-settings').onclick=show;
+ $('settings-close').onclick=()=>{sequence++;$('settings-dialog').close();};
+ $('settings-dialog').addEventListener('cancel',()=>sequence++);
+ return {read};
 }

package/assets/app/template-editor.mjs

@@ -4,20 +4,28 @@ export function templateEditor({api,$,checkout,notice}) {
   const drafts=new Map();
   const key=name=>`runlist:template-draft:${checkout()}:${name}`;
   const current=()=>drafts.get(selected.name);
-  function keep() {if(!selected?.editable)return;try{localStorage.setItem(key(selected.name),JSON.stringify(current()));}catch{feedback('Template draft could not be saved in local editor storage. Keep this dialog open.',true);}}
-  function feedback(text,error=false){$('template-feedback').textContent=text;$('template-feedback').classList.toggle('error',error);}
+  function keep() {if(!selected?.editable)return;try{localStorage.setItem(key(selected.name),JSON.stringify(current()));return true;}catch{feedback('Template draft could not be saved in local editor storage. Keep this dialog open.',true);return false;}}
+  function feedback(text,error=false){$('template-feedback').hidden=!text;$('template-feedback').textContent=text;$('template-feedback').classList.toggle('error',error);}
   function dirty(){const d=current();return selected?.editable&&(d.source!==d.base||d.reset);}
   function render() {
     if(!selected)return;
-    const d=current();$('template-name').textContent=selected.name;$('template-origin').textContent=selected.origin;$('template-description').textContent=selected.description;
+    const d=current(), handoff=selected.kind==='handoff';$('template-name').textContent=selected.label??selected.name;$('template-origin').textContent=selected.origin;$('template-description').textContent=selected.description;
     $('template-config-note').hidden=!selected.configuredSource;$('template-config').hidden=!selected.configuredSource;$('template-config-source').textContent=selected.configuredSource??'';
+    $('template-config-label').textContent=selected.configLabel??'Repository JavaScript source';
+    $('template-config-note').textContent=selected.configNote??'Saving here replaces the configured template with this Markdown.';
+    $('template-tokens').textContent=handoff
+      ? selected.name==='handoff:subagent'?'Keep parent_prompt: {{parent_prompt}} in frontmatter. The CLI fills it from --parent or RUNLIST_PARENT_PROMPT.':'No placeholders required. Keep only the context the next session needs.'
+      :'Placeholders: {{title}}, {{status}}, {{date}}, {{body}}, {{version}}. Keep the metadata fields and body placeholder.';
+    $('template-save-note').textContent=handoff
+      ?'Used for future handoff drafts. Saved in runlist.templates.json.'
+      :'Used for new documents. Saved in runlist.templates.json.';
     $('template-source').value=d.source;$('template-source').readOnly=!selected.editable;$('template-source').hidden=preview;
     $('template-preview').hidden=!preview;
     $('template-preview-tab').disabled=!selected.editable;
     $('template-edit-tab').setAttribute('aria-pressed',String(!preview));$('template-preview-tab').setAttribute('aria-pressed',String(preview));
-    const example=d.source.replace(/\{\{(title|status|date|body|version)\}\}/g,(_,token)=>({title:'Example document',status:selected.name==='prompt'?'pending':selected.name==='plan'?'planned':'active',date:new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),body:'Authored content goes here.',version:catalog.version})[token]);
+    const example=d.source.replace(/\{\{(title|status|date|body|version|parent_prompt)\}\}/g,(_,token)=>({title:'Example document',status:selected.name==='prompt'?'pending':selected.name==='plan'?'planned':'active',date:new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'),body:'Authored content goes here.',version:catalog.version,parent_prompt:'resume-example-session'})[token]);
     $('template-preview').innerHTML=markdownHtml(example);
-    $('template-review-button').disabled=!dirty()||busy;$('template-reset').hidden=!selected.editable||(!selected.overridden&&!selected.configuredSource);
+    $('template-review-button').disabled=!dirty()||busy;$('template-reset').hidden=!selected.editable||(!selected.overridden&&(!selected.configuredSource||handoff));
     $('template-discard').disabled=!dirty()||busy;$('template-tokens').hidden=!selected.editable;
     $('template-review-button').hidden=!selected.editable;$('template-save').hidden=true;$('template-review').hidden=true;
     $('template-save').disabled=busy;$('template-source').disabled=busy;
@@ -30,18 +38,20 @@ export function templateEditor({api,$,checkout,notice}) {
       let saved;try{saved=JSON.parse(localStorage.getItem(key(template.name)));}catch{}
       drafts.set(template.name,saved&&typeof saved.source==='string'&&typeof saved.base==='string'&&('revision'in saved)?saved:{source:template.source,base:template.source,revision:catalog.revision,reset:false});
     }
-    render();feedback(!template.editable?'JavaScript template · edit this source in runlist.config.mjs.':dirty()?'Your template draft is kept. Review it before saving.':template.configuredSource&&!template.overridden?'The editor contains a Markdown override starter; the JavaScript template stays active until you save.':'Choose Edit Markdown or Preview example.');
+    // Saving a different template changes the store revision, not this base.
+    if(current().base===template.source)current().revision=catalog.revision;
+    render();feedback(!template.editable?'Edit this JavaScript template in runlist.config.mjs.':dirty()?'Unsaved changes':'');
   }
-  function list(){ $('template-list').replaceChildren(...catalog.templates.map(template=>{const button=document.createElement('button');button.className='quiet';button.dataset.name=template.name;button.textContent=template.name;button.onclick=()=>select(template);return button;})); }
+  function list(){ $('template-list').replaceChildren(...catalog.templates.map(template=>{const button=document.createElement('button');button.className='quiet';button.dataset.name=template.name;button.textContent=template.label??template.name;button.onclick=()=>select(template);return button;})); }
   $('open-templates').onclick=async()=>{try{catalog=await api('templates');list();select(catalog.templates.find(t=>t.name===selected?.name)??catalog.templates.find(t=>t.name==='plan')??catalog.templates[0]);$('template-dialog').showModal();}catch(error){notice(error.message,true);}};
   $('close-templates').onclick=()=>{$('template-dialog').close();};
   $('template-dialog').addEventListener('cancel',event=>{if(busy)event.preventDefault();});
-  $('template-source').oninput=()=>{const d=current();d.source=$('template-source').value;d.reset=false;keep();$('template-save').hidden=true;$('template-review').hidden=true;$('template-review-button').disabled=!dirty();feedback('Template draft kept in local editor storage.');};
+  $('template-source').oninput=()=>{const d=current();d.source=$('template-source').value;d.reset=false;const kept=keep();$('template-save').hidden=true;$('template-review').hidden=true;$('template-review-button').hidden=false;$('template-review-button').disabled=!dirty();$('template-discard').disabled=!dirty();if(kept)feedback(dirty()?'Unsaved changes':'');};
   $('template-edit-tab').onclick=()=>{preview=false;render();};$('template-preview-tab').onclick=()=>{preview=true;render();};
-  $('template-review-button').onclick=()=>{const d=current();$('template-diff').innerHTML=diffHtml(d.base,d.source);$('template-review').hidden=false;$('template-review').open=true;$('template-save').hidden=false;$('template-save').disabled=!dirty();feedback(d.reset?'Save will remove the Markdown override and use the original template.':'Review this template before saving it for future documents.');};
-  $('template-reset').onclick=()=>{const d=current();d.source=selected.defaultSource;d.reset=true;keep();render();feedback('Review and save to remove the Markdown override and use the original template.');};
+  $('template-review-button').onclick=()=>{const d=current();$('template-diff').innerHTML=diffHtml(d.base,d.source);$('template-review').hidden=false;$('template-review').open=true;$('template-save').hidden=false;$('template-save').disabled=!dirty();$('template-review-button').hidden=true;feedback(d.reset?'Saving restores the original template.':'');};
+  $('template-reset').onclick=()=>{const d=current();d.source=selected.defaultSource;d.reset=true;const kept=keep();render();if(kept)feedback('Review and save to restore the original template.');};
   $('template-discard').onclick=()=>{drafts.set(selected.name,{source:selected.source,base:selected.source,revision:catalog.revision,reset:false});localStorage.removeItem(key(selected.name));render();feedback('Template draft discarded.');};
-  $('template-reload').onclick=async()=>{try{catalog=await api('templates');const name=selected.name;selected=catalog.templates.find(t=>t.name===name);const d=current();d.base=selected.source;d.revision=catalog.revision;keep();list();render();$('template-reload').hidden=true;feedback('Saved template reloaded. Your draft is kept; compare and review it before saving.');}catch(error){feedback(error.message,true);}};
-  $('template-save').onclick=async()=>{if(busy||!dirty())return;const name=selected.name,d=current();busy=true;$('template-save').disabled=true;$('template-dialog').querySelector('.template-layout').inert=true;$('close-templates').disabled=true;try{catalog=await api('templates/save',{name,source:d.source,expectedRevision:d.revision,reset:d.reset});selected=catalog.templates.find(t=>t.name===name);drafts.delete(name);localStorage.removeItem(key(name));busy=false;list();select(selected);feedback('Template saved to runlist.templates.json. New documents use it.');}catch(error){feedback(error.message,true);keep();if(error.code==='template-conflict')$('template-reload').hidden=false;}finally{busy=false;$('template-dialog').querySelector('.template-layout').inert=false;$('template-save').disabled=false;$('close-templates').disabled=false;}};
+  $('template-reload').onclick=async()=>{try{catalog=await api('templates');const name=selected.name;selected=catalog.templates.find(t=>t.name===name);const d=current();d.base=selected.source;d.revision=catalog.revision;keep();list();render();$('template-reload').hidden=true;feedback('Saved template reloaded. Your draft is kept.');}catch(error){feedback(error.message,true);}};
+  $('template-save').onclick=async()=>{if(busy||!dirty())return;const name=selected.name,d=current();busy=true;$('template-save').disabled=true;$('template-dialog').querySelector('.template-layout').inert=true;$('close-templates').disabled=true;try{catalog=await api('templates/save',{name,source:d.source,expectedRevision:d.revision,reset:d.reset});selected=catalog.templates.find(t=>t.name===name);drafts.delete(name);localStorage.removeItem(key(name));busy=false;list();select(selected);feedback('Template saved.');}catch(error){feedback(error.message,true);keep();if(error.code==='template-conflict')$('template-reload').hidden=false;}finally{busy=false;$('template-dialog').querySelector('.template-layout').inert=false;$('template-save').disabled=false;$('close-templates').disabled=false;}};
   document.addEventListener('keydown',event=>{if($('template-dialog').open&&(event.metaKey||event.ctrlKey)&&event.key==='s'){event.preventDefault();$('template-review-button').click();}});
 }

package/assets/app/transport.mjs

@@ -21,8 +21,7 @@ export async function mountDesktop({beforeLeave,bootstrap,notice}) {
   const $=id=>document.getElementById(id);
   $('connect-panel').hidden=true;$('desktop-welcome').hidden=false;$('desktop-open').hidden=false;
   $('disconnect').textContent='Close folder';
-  $('bookmark-empty').textContent='Star a heading to keep it here. Bookmarks stay in Runlist on this computer.';
-  const footer=document.querySelector('.sidebar-footer');footer.replaceChildren(document.createTextNode('Local files · This computer only'),document.createElement('br'));const label=document.createElement('span');label.textContent='Save here. Review local commits in Changes.';footer.append(label);
+  document.querySelector('.sidebar-footer').textContent='';
   async function recent(){const state=await invoke('desktop_status');const root=$('desktop-recents');root.replaceChildren();for(const item of state.recent){const button=document.createElement('button');button.className='quiet recent-checkout';button.textContent=item.path;button.onclick=()=>choose(item.id);root.append(button);}return state;}
   let moving=false;
   async function choose(id){if(moving)return;moving=true;try{

package/bin/runlist.mjs

@@ -3,7 +3,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
-import { resolveConfig } from '../src/config.mjs';
+import { resolveConfig, locateConfig } from '../src/config.mjs';
 import { readPlanStage } from '../src/stages.mjs';
 import { scopeFilingCoverage } from '../src/filing.mjs';
 import { die, warn, levenshtein, isArchivedPath, toRepoPath } from '../src/util.mjs';
@@ -285,7 +285,7 @@ Analyze:
   record <file> <action> --note <reason> Act on a native flag or decision
   decision <file> <id> --disposition <state> --note <reason> Record an outcome
   decisions [doc|id] [--all|--check] Open and held decisions, read from the corpus
-  show <file...> [--json]           One document's card: status, next step, related plans and docs, links
+  show <file...> [--section <h>]    One document's card, outline and open boxes with line numbers; one section
   xref <file...> | --check [--flag] Cross-references: what names it, its decisions, its cited code
 
 Validate & Fix:
@@ -893,6 +893,8 @@ Modes:
                          when a verb says "No authoritative session identity",
                          or on any host runlist has never been tried on.
   --session --json       Machine-readable identity + host-integration state.
+  --prompts              Read-only parent-link findings: linked, inferred, missing, archived,
+                         ambiguous or invalid. Supports --json; never consumes or repairs.
   --statuses             Read-only diagnostic: detect overloaded status
                          buckets where one status holds plans pursuing
                          multiple distinct unstuck-actions. Suggests how
@@ -1295,6 +1297,8 @@ Subcommands:
   show <file-or-slug>        Read-only peek: print the body WITHOUT consuming
                              (triage). \`peek\` is an alias.
   archive <file-or-slug>     Archive a prompt without printing its body
+  link <child...> --parent <resume-name>
+                             Attach existing children without replacing their handoffs
   new <slug> [body]          Create a new prompt (alias for
                              \`runlist new prompt <slug> [body]\`)
 
@@ -1308,6 +1312,14 @@ Pass \`--no-claim\` to read and archive the prompt without starting the plan.
 
 Default prompt statuses: pending, archived.
 
+The default list shows [+ N subagent prompts] on their resume-* parent's line.
+Use --verbose to expand their names and targets.
+Record the parent with \`baton --subagent <task> --parent resume-<name>\`;
+legacy child names sharing the parent's name stem also group. Missing-parent
+children share a separate count. Grouping does not change which prompt is consumed next.
+Showing or consuming a parent also lists its pending children for inspection;
+the children remain pending until explicitly consumed or archived.
+
 Examples:
   runlist prompts                        # pending prompts (default)
   runlist prompts list --verbose         # one row per prompt + target plan ref
@@ -1350,6 +1362,8 @@ Options:
   --message / --body     Inline body (one-liners; prefer @path or stdin)
   --force                Recover another session's plan (explicit path required)
   --subagent             Save subagent-<name> instead of the parent default resume-<name>
+  --parent <resume-name>  Group this --subagent handoff under its parent in prompts listings
+  --template             Print a resume draft (or --subagent draft), using saved Markdown settings
   --replace              Replace exactly one pending handoff; archive its prior text
   --done                 Report a plan handoff done once next_step changed after the prompt was saved
   --json                 Structured repository/session/generated file result
@@ -1362,9 +1376,12 @@ Repo-specific commit hint (runlist.config.mjs):
 The function returns argv; baton shell-quotes each argument before printing.
 
 Examples:
+  runlist baton --template > /tmp/resume.md
   runlist baton @/tmp/draft.md
   runlist baton checkout-fixes @/tmp/draft.md
   runlist baton --subagent totals-review @/tmp/draft.md
+  runlist baton --subagent totals-review --parent resume-session-name @/tmp/draft.md
+  runlist baton --subagent --template --parent resume-session-name > /tmp/child.md
   runlist baton docs/plans/auth.md @/tmp/draft.md
   runlist baton docs/plans/auth.md @/tmp/new-draft.md --replace
   runlist baton --status paused --note "blocked on review" @/tmp/d.md
@@ -1396,6 +1413,15 @@ than releasing the parent plan. A child owning its own plan can hand it off.
 Matching prefixes are kept once; conflicting or nested prefixes are refused.
 Existing prompts keep their names. --subagent --replace refuses a parent-named
 handoff rather than reclassifying it.
+Use --parent resume-<name> to record the owning parent prompt (it may be saved
+later). Prompt listings show linked child counts on that parent's line; legacy child
+names sharing its name stem also group. Consumption order is unchanged.
+The child draft template covers Task, State, Next, Evidence and Boundaries.
+Its parent_prompt field travels with the draft. A launcher can instead pass
+RUNLIST_PARENT_PROMPT to the child; explicit --parent wins and replacement
+preserves a retained link. An unlinked child save warns with a repair command.
+Keep the full record at a durable repo-relative path, with commits and checked
+results. On completion, say what the parent must record and what remains.
 
 Slug mode (no plan involved) saves resume-<slug> by default without a status change or
 commit. A bare word that names a plan is treated as that plan.
@@ -1545,18 +1571,32 @@ remain owned by their CLI sessions; coordinate/release them before a human save.
 Metadata and lifecycle changes continue through the CLI. Ctrl+C stops the app.
 --dry-run previews startup without opening a server or writing editor state.
 `,
-  show: `runlist show <file...> — one document's card, read-only
-
-  runlist show <file>           title, status, next step, blockers, checklist,
-                                related plans and docs, documents linked from the body
-  runlist show <a> <b> --json   [{ path, type, title, status, summary, currentState,
-                                   nextStep, blockers, checklist, updated,
-                                   related: [{ field, ref, path, exists, title, status, type }],
-                                   links: [{ path, title, status, type }] }]
-
-A file is a path, filename or slug, as for \`use\`. Nothing is claimed or
-written. With --json a file that is not found is { path, error } rather than
-an exit.`,
+  show: `runlist show <file...> — a document in a few KB, read-only
+
+  runlist show <file>           card (title, status, next step, blockers, related
+                                plans and docs, body links), then the outline and
+                                open boxes with line numbers, then the other
+                                frontmatter fields by name
+  runlist show <file> --section "<heading>"
+                                that section, every line numbered, to the next
+                                heading at the same or a higher level
+      --from <line>             continue a section read that was cut
+      --all                     every open box, not the first 30
+      --card                    the card only
+      --frontmatter             the frontmatter as written, long values collapsed
+      --json                    the same as data; a section read is
+                                { path, query, heading, from, to, next, rows, others }
+
+Read a plan or long doc this way, then one section at a time, never whole. A
+heading matches case-insensitively: exact first, then as a prefix, then as a
+substring; other matches are named. A section read stops at 500 lines or
+60 KB and prints the command that continues it. Headings and boxes inside code
+fences are ignored. Several files at once get a shorter outline each.
+
+A file is a path, filename or slug, as for \`use\`, and any Markdown file in
+the repo works. Nothing is claimed or written. With --json a file that is not
+found is { path, error } rather than an exit; a heading that matches nothing
+exits 1 and lists the headings.`,
 
   model: `runlist model — the local model behind summaries and lint
 
@@ -1909,7 +1949,7 @@ async function main() {
   const doctorSubMode = command === 'doctor' && (
     args.includes('--statuses') || args.includes('--migrate-template')
     || args.includes('--migrate-prompts') || args.includes('--frontmatter-fix')
-    || args.includes('--project')
+    || args.includes('--project') || args.includes('--prompts')
   );
   const doctorExplicitApply = args.includes('--apply') || args.includes('--yes');
   const effectiveDryRun = dryRun || (command === 'doctor' && !doctorSubMode && !doctorExplicitApply);
@@ -1948,6 +1988,15 @@ async function main() {
     return;
   }
 
+  if (command === 'baton' && restArgs.includes('--template')) {
+    _suppressObservability = true;
+    requireCommandPolicy(command, dispatchPolicy);
+    try { restArgs = validateCommandArgs(command, restArgs); } catch (err) { die(err.message); }
+    const { runBaton } = await import('../src/baton.mjs');
+    await runBaton(restArgs, locateConfig(process.cwd(), explicitConfig), { dryRun });
+    return;
+  }
+
   if (command === 'desktop') {
     requireCommandPolicy(command, dispatchPolicy);
     try { restArgs=validateCommandArgs(command,restArgs); } catch(err) { die(err.message); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/plugins/runlist-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist-codex",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
   "author": {
     "name": "Reo Owens"