heyquilt 0.3.90 → 0.3.106

package/src/relay-upstream.js

@@ -7,9 +7,9 @@
 // and upstream branch the branch follows, and the last commit a folder on it was at while
 // in step with the session; then, every so often, it asks GitHub whether that upstream
 // moved on, and if it is strictly ahead, merges its files into the branch document the
-// same way a folder would (upstream.js planCatchUp). All or nothing: a clash is handed to
-// one hosted agent on that branch as a task (clash.js), and lands once its writes make the
-// merge clean. Never a history merge, never anything written to GitHub.
+// same way a folder would (upstream.js planCatchUp): where both changed the same lines, Quilt
+// combines them itself, the newer edit keeping them, and tells whoever's lines lost
+// (relay-clash.js). Nobody is asked to merge. Never a history merge, never anything written to GitHub.
 //
 // The relay has no git: the commit it records is "the session's files are this commit plus
 // the session's work". A folder that comes back behind its upstream follows it like a
@@ -21,13 +21,10 @@ import { planCatchUp, publishedOf } from './upstream.js'
 import { applyTextDiff } from './textdiff.js'
 import { looksBinary, sha1 } from './fsutil.js'
 import { LARGE_FILE_BYTES, MAX_TEXT_BYTES, makeIgnore, scopeIgnore, isIgnored, isSafeRelPath } from './pathrules.js'
-import { mergeAdditive } from './merge3.js'
-import { readTasks, addTask, updateTask } from './tasks.js'
-import { addComment, MAX_COMMENT } from './task-comments.js'
-import { changeRefusal } from './session-access.js'
-import { HistoryLog, lineDiff } from './history.js'
-import { clashTaskId, clashTitle, clashFiles, relayClashBrief } from './clash.js'
-import { RELAY_BY } from './branches.js'
+import { unionMatcher } from './merge3.js'
+import { readTasks, updateTask } from './tasks.js'
+import { HistoryLog } from './history.js'
+import { RELAY_BY, isRelay } from './branches.js'
 
 /** How often the relay asks GitHub about a branch nobody's folder is on (per branch). */
 export const UPSTREAM_CHECK_MS = 10 * 60 * 1000
@@ -38,7 +35,7 @@ export const MAX_BACKOFF_MS = 6 * 60 * 60 * 1000
 export const FIRST_BACKOFF_MS = 15 * 60 * 1000
 /** GitHub's compare lists at most this many files: more and the relay leaves it to a folder. */
 const COMPARE_FILES = 300
-/** A clash assignee with no progress this long (files unchanged, task not moved) is handed on. */
+/** Kept for server.js's settings (an older clash task's assignee was handed on after this long); unused since Quilt merges on its own. */
 export const CLASH_IDLE_MS = 15 * 60 * 1000
 /** quilt_sync_branch asks GitHub at most this often per branch (Room.syncUpstreamNow). */
 export const SYNC_EVERY_MS = 60 * 1000
@@ -490,16 +487,13 @@ async function quiltignoresAt (gh, sha, list) {
   return out
 }
 
-const isText = (k) => typeof k === 'string' && !k.startsWith('bin:')
-const regionKey = (lines) => sha1(Buffer.from(lines.join('\n'), 'utf8'))
-/** The session's side of each region of a file that clashes with upstream, by fingerprint (a rewrite of those lines is the merge). */
-export const clashRegions = (b, o, t) => isText(b) && isText(o) && isText(t) ? mergeAdditive(b, o, t).conflicts.map((c) => regionKey(c.ours)) : null
-
 /**
  * One look at branch `key` (the caller checked relayLooks). Asks GitHub for the upstream's
  * head; when it is strictly ahead of the recorded commit, reads every changed file at both
- * ends and merges them into the branch document, or hands the clash to a hosted agent.
- * Returns what happened: { state, ... } for tests and the log. Never throws.
+ * ends and merges them into the branch document, combining what both sides changed (the
+ * newer edit keeps the lines both changed: the newest compared commit's time against the
+ * session's last edit of the file). Returns what happened: { state, ... } for tests and the
+ * log. Never throws.
  */
 export async function checkBranch (room, key, { fetch, now = () => Date.now(), log = () => {}, fallbackToken = null } = {}) {
   const recs = upstreamsOf(room)
@@ -629,53 +623,27 @@ export async function checkBranch (room, key, { fetch, now = () => Date.now(), l
   const baseMap = new Map([...files].map(([rel, f]) => [rel, f.base]))
   const theirs = new Map([...files].map(([rel, f]) => [rel, f.head]))
   const disk = (rel) => docKey(e, rel)
-  let plan = planCatchUp({ changes, base: baseMap, theirs, disk, published: publishedOf(room.doc) })
-  const why = (c) => tooLarge.has(c.path) ? { ...c, why: `too large for the relay to bring in (binaries over ${LARGE_FILE_BYTES / 1024} KB, text over ${MAX_TEXT_BYTES / 1024 / 1024} MB): a member's folder brings it in` } : c
-  let resolved = []
-  if (plan.conflicts.length && rec.clash) {
-    // The files handed out with the clash that count as merged: all of them once its assignee
-    // moved the task to QA or Done (for this commit); otherwise each one rewritten since in the
-    // lines that clashed (no markers left), so it merges cleanly with the new commit around them.
-    // The session keeps the merged lines, takes the commit's other changes, and the rest is planned again.
-    const was = rec.clash.files || {}
-    const regions = rec.clash.regions || {}
-    const settled = !!(rec.clash.settled && rec.clash.sha === head)
-    resolved = plan.conflicts.map((c) => c.path).filter((rel) => {
-      const d = disk(rel)
-      if (!(rel in was) || d === undefined) return false
-      if (settled) return !hasMarkers(d) // the assignee says it's merged: never with conflict markers left
-      if (was[rel] === fingerprint(d) || hasMarkers(d)) return false
-      const b = baseMap.get(rel)
-      const t = theirs.get(rel)
-      if (!isText(b) || !isText(d) || !isText(t)) return true // a deletion or a binary: changed since is all there is to go on
-      const old = regions[rel]
-      return !old || mergeAdditive(b, d, t).conflicts.every((c) => !old.includes(regionKey(c.ours)))
-    })
-    if (resolved.length) {
-      plan = planCatchUp({ changes: new Map([...changes].filter(([rel]) => !resolved.includes(rel))), base: baseMap, theirs, disk, published: publishedOf(room.doc) })
-      if (!plan.conflicts.length) {
-        for (const rel of resolved) {
-          const b = baseMap.get(rel)
-          const d = disk(rel)
-          const t = theirs.get(rel)
-          if (!isText(b) || !isText(d) || !isText(t)) continue
-          const merged = mergeAdditive(b, d, t).text
-          if (merged !== d) plan.writes.set(rel, merged)
-        }
-      }
-    }
-  }
+  // Which edit is newer, for the lines both sides changed: the session's last edit of the file against GitHub's newest commit here.
+  const commits = Array.isArray(cmp.commits) ? cmp.commits : []
+  const newest = commits.at(-1) || null
+  const ghAt = newest && newest.commit ? Date.parse((newest.commit.committer && newest.commit.committer.date) || (newest.commit.author && newest.commit.author.date) || '') || 0 : 0
+  const ghSide = newest ? { name: (newest.commit && newest.commit.author && newest.commit.author.name) || (newest.author && newest.author.login) || rec.name, sha: newest.sha || head, ts: ghAt } : null
+  const parties = new Map()
+  const partyOf = (rel) => { if (!parties.has(rel)) parties.set(rel, lastEditor(e, rel)); return parties.get(rel) }
+  const oursNewer = (rel) => ((partyOf(rel) || {}).ts || 0) > ghAt + 999 // a commit's whole second is its own
+  const union = unionOf(e)
+  const plan = planCatchUp({ changes, base: baseMap, theirs, disk, published: publishedOf(room.doc), oursNewer, union })
   if (plan.conflicts.length) {
-    const conflicts = plan.conflicts.map(why)
-    const r = handClash(room, key, rec, { head, base, behind, conflicts, disk, baseMap, theirs, now: now() })
-    said(r.problem || null)
-    return done({ state: 'clash', head, conflicts, task: r.task || null, resolved })
+    // Files the relay can't read (too large for it): nothing comes in until a member's folder brings them in (all or nothing: one commit is recorded).
+    const list = plan.conflicts.map((c) => c.path)
+    said(`${rec.name} changes ${list.slice(0, 4).join(', ')}${list.length > 4 ? ' and more' : ''}, too large for the relay to read: a member's folder on ${key} brings ${list.length === 1 ? 'it' : 'them'} in`)
+    return done({ state: 'too-large', head, files: list })
   }
   // A file someone holds is never written under them (as a folder's bring-in waits, Session.bringIn):
   // only the clash's files, held for its merge. The bring-in waits until they let go of it.
   for (const rel of plan.writes.keys()) {
     const c = room.claimFor ? room.claimFor(rel, key) : null
-    if (c && !(rec.clash && c.clash === rec.clash.task)) {
+    if (c) {
       said(`${c.by} holds ${rel}: the relay brings ${rec.name} in once they let go of it (quilt_release, or quilt_handoff)`)
       rec.waitingOn = { path: rel, by: c.by, pattern: c.pattern } // looked at again as soon as that claim goes (Room.noteClaimsChanged)
       return done({ state: 'waiting', head, held: rel, by: c.by })
@@ -717,9 +685,12 @@ export async function checkBranch (room, key, { fetch, now = () => Date.now(), l
   rec.sha = head
   rec.relayHead = head
   rec.brought = { count: behind, files: written, at: now(), head }
+  // Whoever's lines lost is told: a direct message for the session's, the activity log for GitHub's (relay-clash.js).
+  const { tellAutoMerge } = await import('./relay-clash.js')
+  for (const m of plan.merged) tellAutoMerge(room, key, { path: m.path, lost: m.lost, deleted: m.deleted || null, session: partyOf(m.path), github: ghSide, upstream: rec.name, head, now: now() })
   said(null)
-  closeLanded(room, key, rec, `Brought in at ${head.slice(0, 7)}: ${RELAY_BY} merged ${plural(behind, 'commit')} from ${rec.name} into ${key}${resolved.length ? `, keeping the merged ${resolved.join(', ')}` : ''}.`)
-  return done({ state: 'brought', head, count: behind, files: written, resolved })
+  closeLanded(room, key, rec, `Brought in at ${head.slice(0, 7)}: ${RELAY_BY} merged ${plural(behind, 'commit')} from ${rec.name} into ${key}.`)
+  return done({ state: 'brought', head, count: behind, files: written, merged: plan.merged.map((m) => ({ path: m.path, lost: m.lost.length ? m.lost[0].side : null, ...(m.deleted ? { deleted: m.deleted } : {}) })) })
 }
 
 /** The relay's clash task on `key` is done: the session is at or past its commit. */
@@ -732,119 +703,18 @@ export function closeLanded (room, key, rec, verified) {
   delete rec.clash
 }
 
-/**
- * A clash on `key`, handed to ONE hosted agent on that branch as a task: the same id a
- * member's Quilt would give it (clash.js), assigned by name, its description listing each
- * file and why, then the change from upstream for each file. Returns { task } or { problem }.
- */
-export function handClash (room, key, rec, { head, base, behind, conflicts, disk, baseMap, theirs, now }) {
-  const upstream = rec.name
-  const n = plural(conflicts.length, 'file')
-  const paths = conflicts.map((c) => c.path)
-  const mayTake = (a) => paths.every((rel) => !changeRefusal(a, rel))
-  const tasks = readTasks(room.tasks)
-  let task = rec.clash ? tasks.find((t) => t.id === rec.clash.task) || null : null
-  if (!task) task = tasks.find((t) => t.id === clashTaskId(key, head)) || null
-  // Hosted agents first (not a chat link: it can only add new files), then CLI agents connected on the branch.
-  const cli = [...room.conns.keys()]
-    .filter((ws) => ws.branch === key && ws.pass && ws.pass.kind === 'agent' && room.names && room.names.get(ws))
-    .map((ws) => ({ ...(room.access.get(ws) || {}), name: room.names.get(ws), who: room.claimant(ws) }))
-    .filter((a) => a.role)
-  const hosted = hostedOn(room, key).filter((a) => !a.chat).map((a) => ({ ...a, who: { name: a.name, id: a.id, talk: a.talk !== false, branch: key } }))
-  const agents = [...hosted, ...cli].filter(mayTake)
-    .filter((a, i, all) => all.findIndex((x) => x.name === a.name) === i)
-  const id = task ? task.id : clashTaskId(key, head)
-  // Taken off the board for this commit: not again (a newer commit may be handed out).
-  if (!task && rec.clash && rec.clash.sha === head) return { problem: `${n} clash with the session's work on ${key} (task ${rec.clash.task} was taken off the board): a member's folder on ${key} has to bring ${upstream} in` }
-  if (!task && !agents.length) return { problem: `${behind} commit${behind === 1 ? '' : 's'} from ${upstream} clash with the session's work on ${key} in ${paths.slice(0, 4).join(', ')}${paths.length > 4 ? ' and more' : ''}, and no agent that may change them is on ${key} to merge them` }
-  const same = rec.clash && rec.clash.task === id
-  const files = { ...(same ? rec.clash.files : {}) }
-  const regions = { ...(same ? rec.clash.regions || {} : {}) }
-  for (const rel of paths) {
-    if (rel in files) continue
-    files[rel] = fingerprint(disk(rel))
-    const r = clashRegions(baseMap.get(rel), disk(rel), theirs.get(rel))
-    if (r) regions[rel] = r
-  }
-  const brief = () => relayClashBrief({ branch: key, upstream, sha: head, base, behind, conflicts, compare: `https://${rec.repo}/compare/${base.slice(0, 12)}...${head.slice(0, 12)}` })
-  const post = (text) => { try { addComment(room.doc, room.taskComments, readTasks(room.tasks), { taskId: id, by: RELAY_BY, text }, ORIGIN) } catch {} }
-  const diffs = () => {
-    for (const c of conflicts.slice(0, 8)) {
-      const b = baseMap.get(c.path)
-      const t = theirs.get(c.path)
-      const head7 = head.slice(0, 7)
-      const intro = `What ${upstream} changed in ${c.path} (${base.slice(0, 7)} → ${head7}):`
-      if (typeof b !== 'string' && b !== null) { post(`${intro} not readable by the relay; see https://${rec.repo}/blob/${head7}/${c.path}`); continue }
-      if (typeof t !== 'string' && t !== null) { post(`${intro} not readable by the relay; see https://${rec.repo}/blob/${head7}/${c.path}`); continue }
-      if ((b && b.startsWith('bin:')) || (t && t.startsWith('bin:'))) { post(`${intro} a binary file; see https://${rec.repo}/blob/${head7}/${c.path}`); continue }
-      const room4 = MAX_COMMENT - intro.length - 20
-      const d = t === null ? `(deleted in ${upstream})` : lineDiff(b || '', t, { max: room4 })
-      post(`${intro}\n\`\`\`diff\n${d.slice(0, room4)}\n\`\`\``)
-    }
-  }
-  // Its assignee (or the member whose AI session it is) connected on the branch: its own Quilt
-  // carries the merge on; the relay never hands it on nor takes its files.
-  const present = !!task && connectedAs(room, key, task.assignee)
-  // No progress (the clashing files unchanged, the task not moved) for a while: handed on to the next agent.
-  const progressKey = JSON.stringify([task && task.assignee, task && task.column, paths.map((rel) => fingerprint(disk(rel)))])
-  const idleMs = (room.cfg && Number.isFinite(room.cfg.clashIdleMs)) ? room.cfg.clashIdleMs : CLASH_IDLE_MS
-  const was = rec.clash && rec.clash.task === id && rec.clash.progress
-  const progress = was && was.key === progressKey ? was : { key: progressKey, since: now }
-  const stalled = !!task && !present && now - progress.since > idleMs && agents.some((a) => a.name !== task.assignee)
-  if (!task) {
-    const to = agents[0]
-    try {
-      task = addTask(room.doc, room.tasks, { id, title: clashTitle({ upstream, behind, conflicts }), by: RELAY_BY, assignee: to.name, forAi: false, tool: '', files: clashFiles(conflicts) }, ORIGIN)
-    } catch (err) { return { problem: `${n} clash with the session's work on ${key}, and the relay couldn't put the merge on the board (${err.message})` } }
-    room.log(`[${room.name}] ${key}: the clash with ${upstream} ${head.slice(0, 7)} went to ${to.name} (task ${id})`)
-    post(brief())
-    diffs()
-  } else {
-    const fresh = !rec.clash || rec.clash.sha !== head
-    const patch = { id: task.id }
-    if (fresh) { patch.title = clashTitle({ upstream, behind, conflicts }); patch.files = clashFiles(conflicts) }
-    // Its assignee left the branch (no longer an agent on it), or made no progress for a while, and
-    // another agent is there: theirs now. Never while its assignee's member is connected on the branch.
-    const assigneeHere = present || agents.some((a) => a.name === task.assignee)
-    const next = agents.find((a) => a.name !== task.assignee)
-    if (!present && next && (!assigneeHere || stalled)) { patch.assignee = next.name; patch.forAi = false; patch.tool = '' }
-    const why = patch.assignee && assigneeHere ? `${task.assignee} made no progress on it for ${Math.round(idleMs / 60000)} minutes` : `the last assignee is no longer on \`${key}\``
-    // Moved to Done while it still clashes (by someone else, or for an older commit): open again.
-    if (task.column === 'done') patch.column = 'doing'
-    if (Object.keys(patch).length > 1) {
-      try { task = updateTask(room.doc, room.tasks, patch, ORIGIN) } catch {}
-    }
-    if (present) {
-      // Its member's own Quilt has it: nothing to add.
-    } else if (!rec.clash || rec.clash.task !== task.id) {
-      // A task a member's Quilt wrote for this commit, its folder now offline: the relay carries it on.
-      post(`${patch.assignee ? `Handed to ${patch.assignee}: no folder on \`${key}\` is online, so the relay carries this merge on in the session.\n\n` : ''}${brief()}`)
-      diffs()
-    } else if (fresh) {
-      post(`${upstream} moved on to ${head.slice(0, 7)}.\n\n${brief()}`)
-      diffs()
-    } else if (patch.assignee) {
-      post(`Handed to ${patch.assignee}: ${why}.\n\n${brief()}`)
-    } else if (patch.column) {
-      post(`Open again: ${head.slice(0, 7)} from ${upstream} still clashes with the session's work on \`${key}\`. Quilt closes this task by itself once the merge lands: no need to move it.`)
-    }
-  }
-  const keep = rec.clash && rec.clash.task === task.id
-  // Its assignee holds the clashing files while it merges (asked for in their queues when someone
-  // else holds one), so nobody else edits them meanwhile; let go of when the task is done (Room.dropClashClaims).
-  const holder = present ? null : agents.find((a) => a.name === task.assignee)
-  const had = keep && rec.clash.claims && rec.clash.claims.by === task.assignee ? rec.clash.claims : { by: task.assignee, paths: [] }
-  const toClaim = paths.filter((rel) => !had.paths.includes(rel))
-  if (holder && toClaim.length && room.claimClashFiles) {
-    const r = room.claimClashFiles(holder.who, task.id, toClaim, { upstream })
-    had.paths = [...had.paths, ...r.claimed, ...r.asked.map((x) => x.path)]
-    if (r.asked.length) post(`${r.asked.map((x) => `${x.holder} holds ${x.path}`).join('; ')}: asked for ${r.asked.length === 1 ? 'it' : 'them'} in the file queue for ${task.assignee}, who gets ${r.asked.length === 1 ? 'it' : 'them'} with their context when they hand ${r.asked.length === 1 ? 'it' : 'them'} over.`)
-  }
-  const moved = progress.key !== JSON.stringify([task.assignee, task.column, paths.map((rel) => fingerprint(disk(rel)))])
-  rec.clash = { task: task.id, sha: head, base, files, regions, claims: had, progress: moved ? { key: JSON.stringify([task.assignee, task.column, paths.map((rel) => fingerprint(disk(rel)))]), since: now } : progress, at: keep ? rec.clash.at : now, ...(keep && rec.clash.settled && rec.clash.sha === head ? { settled: rec.clash.settled } : {}) }
-  // The room's clash record, as a member's Quilt keeps it: a folder that comes back finds the same task.
-  try { room.doc.transact(() => room.doc.getMap('clashes').set(key, { task: task.id, sha: head, upstream, ts: now }), ORIGIN) } catch {}
-  return { task: task.id }
+/** The member who last changed `rel` on a branch document (not the relay, not a pull): { name, ts }, or null. */
+function lastEditor (e, rel) {
+  let best = null
+  for (const h of e.doc.getArray('history').toArray()) if (h && h.path === rel && !h.pulled && !h.seed && h.by && !isRelay(h.by) && (!best || (h.ts || 0) >= best.ts)) best = { name: h.by, ts: h.ts || 0 }
+  return best
+}
+
+/** The merge=union matcher from the session's .gitattributes files. */
+function unionOf (e) {
+  const texts = []
+  for (const [rel, t] of e.files) if (rel === '.gitattributes' || rel.endsWith('/.gitattributes')) texts.push([rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : '', t.toString()])
+  return unionMatcher(texts)
 }
 
 /** What a hosted agent (or a member's AI) is told when the relay can't read a private repository. */
@@ -863,12 +733,12 @@ const ago = (ts, now = Date.now()) => {
 export function describeRelayCheck (r, rec, key, room = null) {
   const up = (rec && rec.name) || 'its upstream'
   if (!r) return `The relay didn't look at ${up} for \`${key}\`.`
-  if (r.state === 'brought') return `Brought ${plural(r.count, 'commit')} from ${up} into \`${key}\` (${plural(r.files, 'file')}), merged with the session's uncommitted work${r.resolved && r.resolved.length ? `, keeping the merged ${r.resolved.join(', ')}` : ''}. \`${key}\` is up to date with ${up} (${r.head.slice(0, 7)}).`
-  if (r.state === 'up-to-date') return `\`${key}\`: up to date with ${up} (${r.head.slice(0, 7)}).`
-  if (r.state === 'clash') {
-    const t = room && r.task ? readTasks(room.tasks).find((x) => x.id === r.task) : null
-    return `Nothing brought in: ${up} (${r.head.slice(0, 7)}) clashes with the session's uncommitted work on \`${key}\` in:\n${(r.conflicts || []).map((c) => `- ${c.path}: ${c.why}`).join('\n')}\n${r.task ? `Task ${r.task} on the board${t && t.assignee ? ` (${t.assignee})` : ''}: write each merged file (quilt_write_file, or in your folder), then move the task to QA. The merge lands as soon as the relay sees it.` : (rec && rec.problem) || ''}`
+  if (r.state === 'brought') {
+    const lost = (r.merged || []).filter((m) => m.lost)
+    return `Brought ${plural(r.count, 'commit')} from ${up} into \`${key}\` (${plural(r.files, 'file')}), merged with the session's uncommitted work${lost.length ? `; where both changed the same lines of ${lost.map((m) => m.path).slice(0, 4).join(', ')}, the newer edit was kept (the other lines are in the file's history)` : ''}. \`${key}\` is up to date with ${up} (${r.head.slice(0, 7)}).`
   }
+  if (r.state === 'up-to-date') return `\`${key}\`: up to date with ${up} (${r.head.slice(0, 7)}).`
+  if (r.state === 'too-large') return `Nothing brought in yet: ${up} (${r.head.slice(0, 7)}) changes ${(r.files || []).join(', ')}, too large for the relay to read; a member's folder on \`${key}\` brings ${(r.files || []).length === 1 ? 'it' : 'them'} in. Nothing to merge by hand.`
   if (r.state === 'moved-on') return `A folder on \`${key}\` that brings commits in itself came online, so the relay left it to that folder.`
   if (r.state === 'recovered') return `The commit the session's files on \`${key}\` were measured from wasn't on GitHub (a folder's local commit, since dropped); the relay follows ${up} at ${r.head.slice(0, 7)} now. Nothing to bring in from a commit it can't read; the session's files stay as they are.`
   if (r.state === 'gone') return `Nothing brought in: ${up} isn't on GitHub any more (deleted after its merge?). \`${key}\` stays in the session as it is.`

package/src/releases.js

@@ -1,14 +1,21 @@
 // Release notes and the update check. RELEASES.md (shipped with the app) says what changed
-// in each version; GitHub's latest release says whether a newer build exists.
+// in each version; the latest release says whether a newer build exists. The releases are on a
+// private repository, so the app asks the accounts API for them (src/api/releases.js) and
+// downloads from heyquilt.com, which sends it on to the file.
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { getSettings, saveSettings } from './settings.js'
+import { apiUrl } from './account.js'
 
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
 export const REPO = 'DanielCarmichaelGit/heyquilt'
-const LATEST_API = `https://api.github.com/repos/${REPO}/releases/latest`
-const RELEASES_PAGE = `https://github.com/${REPO}/releases`
+export const SITE = 'https://heyquilt.com'
+/** Where every build is downloaded: heyquilt.com/download/<file> (the latest release's). */
+export const DOWNLOADS = `${SITE}/download`
+/** The one line that installs the command line on a Linux server or cloud machine. */
+export const LINUX_INSTALL = `curl -fsSL ${SITE}/install.sh | sh`
+const latestApi = () => `${apiUrl()}/v1/releases/latest`
 const CACHE_MS = 10 * 60 * 1000
 
 /** The version this app is, from package.json. */
@@ -63,7 +70,7 @@ export function downloadUrl (platform = process.platform, arch = process.arch) {
     : platform === 'win32' ? 'quilt-windows-x64.exe'
       : platform === 'linux' ? `quilt-linux-${arch === 'arm64' ? 'arm64' : 'x86_64'}.AppImage`
         : null
-  return file ? `${RELEASES_PAGE}/latest/download/${file}` : `${RELEASES_PAGE}/latest`
+  return file ? `${DOWNLOADS}/${file}` : SITE
 }
 
 /** The notes inside a GitHub release body written by releaseNotesBody (or by hand in that shape). */
@@ -75,19 +82,19 @@ function parseGitHubBody (body) {
 
 const cache = new Map() // url -> { at, release }
 /**
- * The newest release on GitHub: { version, url, date, summary, items }, or null when it can't be
+ * The newest release (asked of the accounts API): { version, url, date, summary, items }, or null when it can't be
  * reached and nothing is cached. Asks at most every ten minutes; a failed refresh keeps the last answer.
  */
-export async function latestRelease ({ url = process.env.QUILT_RELEASES_URL || LATEST_API, now = Date.now, timeoutMs = 6000 } = {}) {
+export async function latestRelease ({ url = process.env.QUILT_RELEASES_URL || latestApi(), now = Date.now, timeoutMs = 6000 } = {}) {
   const hit = cache.get(url)
   if (hit && now() - hit.at < CACHE_MS) return hit.release
   try {
     const res = await fetch(url, { headers: { accept: 'application/vnd.github+json', 'user-agent': `quilt/${currentVersion()}` }, signal: AbortSignal.timeout(timeoutMs) })
-    if (!res.ok) throw new Error(`GitHub answered ${res.status}`)
+    if (!res.ok) throw new Error(`the release check answered ${res.status}`)
     const r = await res.json()
     const version = String(r.tag_name || '').replace(/^v/, '')
     if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error('no version in the release')
-    const release = { version, url: r.html_url || `${RELEASES_PAGE}/tag/v${version}`, date: String(r.published_at || '').slice(0, 10), ...parseGitHubBody(r.body) }
+    const release = { version, url: r.html_url || SITE, date: String(r.published_at || '').slice(0, 10), ...parseGitHubBody(r.body) }
     cache.set(url, { at: now(), release })
     return release
   } catch {
@@ -120,7 +127,7 @@ export function releaseNotesBody (release) {
     '- Mac (Intel): quilt-mac-x64.dmg',
     '- Windows: quilt-windows-x64.exe',
     '- Linux desktop: quilt-linux-x86_64.AppImage (Intel/AMD), quilt-linux-arm64.AppImage (ARM)',
-    `- Linux servers and cloud machines (no desktop): \`curl -fsSL ${RELEASES_PAGE}/latest/download/install.sh | sh\``,
+    `- Linux servers and cloud machines (no desktop): \`${LINUX_INSTALL}\``,
     '',
     '**Note on signing:** these builds are unsigned (no Apple Developer ID / notarization, no Windows code-signing certificate configured). Windows SmartScreen or macOS Gatekeeper may warn on first launch.',
     '',

package/src/runner.js

@@ -101,7 +101,7 @@ export async function describeOtherSync (dir) {
  * optionally overrides the relay address given out in invites (e.g. a public
  * tunnel URL when the relay runs on this machine).
  */
-export async function runSession ({ dir, conn, name, tool, color = null, shareByDefault = true, summarizeByDefault = false, joined = false, prefer = 'remote', inviteServer, onLog, onFatal, onDebug, kind = 'human', agentFeed = true, readerOptions = {}, passes = null, identity = null, startName = '', startAgentCommits = '', workspace = '' }) {
+export async function runSession ({ dir, conn, name, tool, color = null, shareByDefault = true, summarizeByDefault = false, joined = false, prefer = 'remote', inviteServer, onLog, onFatal, onDebug, kind = 'human', agentFeed = true, readerOptions = {}, passes = null, identity = null, startName = '', startAgentCommits = '', workspace = '', apiAuth = null }) {
   dir = path.resolve(dir)
   if (!/^wss?:\/\//.test(conn.server)) throw new Error('The relay address must start with ws:// or wss://')
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true })
@@ -162,7 +162,8 @@ export async function runSession ({ dir, conn, name, tool, color = null, shareBy
   // The pass may have named us differently from the name we started with.
   if (session.name !== name) saveName(session.name)
   session.on('identity', ({ name }) => saveName(name))
-  const control = await startControl(session, { invite, viewInvite, joined })
+  // apiAuth: { api, token } for the accounts API as this session's person or agent (secrets, `quilt run`).
+  const control = await startControl(session, { invite, viewInvite, joined, apiAuth })
   // Work for this person's AI can run on its own here, when they turned that on (autowork.js).
   autowork().attach(session)
   remember({ dir, room: conn.room, server: conn.server, name: session.name, tool, kind, workspace: savedWorkspace })

package/src/secret-import.js

@@ -0,0 +1,55 @@
+// Import .env (the app's Secrets card): finds a session folder's .env files and says, by name
+// only, what each holds and where it would go. The values are read again only to send them
+// straight to the vault (ui-server.js), and the file can be deleted after.
+import fs from 'node:fs'
+import path from 'node:path'
+import { parseDotenv, guessUpstream, cleanSecretName } from './ui/secret-rules.js'
+
+const ENV_FILE = /^\.env(\.[A-Za-z0-9_.-]+)?$/
+// Templates people commit on purpose: never secrets.
+const TEMPLATE = /\.(example|sample|template|dist|defaults)$/i
+const MAX_FILE = 256 * 1024
+
+/** The .env files at the top of each folder: [{ path, rel, entries: [{ name, upstream?, format?, skip? }] }]. Never a value. */
+export function envFilesIn (dirs) {
+  const out = []
+  const many = new Set(dirs).size > 1
+  for (const dir of [...new Set(dirs.filter(Boolean))]) {
+    let names = []
+    try { names = fs.readdirSync(dir) } catch { continue }
+    for (const n of names.filter((x) => ENV_FILE.test(x) && !TEMPLATE.test(x)).sort()) {
+      const file = path.join(dir, n)
+      let text
+      try {
+        const st = fs.statSync(file)
+        if (!st.isFile() || st.size > MAX_FILE) continue
+        text = fs.readFileSync(file, 'utf8')
+      } catch { continue }
+      const entries = parseDotenv(text).map(({ name, value }) => {
+        try { cleanSecretName(name) } catch { return { name, skip: 'not a secret name (capitals, digits and underscores)' } }
+        if (!value) return { name, skip: 'empty' }
+        const g = guessUpstream(name, value)
+        return g.skip ? { name, skip: g.skip } : { name, ...(g.upstream ? { upstream: g.upstream, format: g.format } : {}) }
+      })
+      out.push({ path: file, rel: many ? `${path.basename(dir)}/${n}` : n, entries })
+    }
+  }
+  return out
+}
+
+/** One of `files` (from envFilesIn) by its path, or an error: nothing else is ever read or deleted. */
+export function knownEnvFile (files, file) {
+  const f = files.find((x) => x.path === String(file || ''))
+  if (!f) throw Object.assign(new Error('That .env file is not in this session\'s folder any more.'), { status: 400 })
+  return f
+}
+
+/** The values of `names` in an .env file, for the vault alone. */
+export function envValues (file, names) {
+  const want = new Set(names)
+  const values = {}
+  for (const { name, value } of parseDotenv(fs.readFileSync(file, 'utf8'))) if (want.has(name)) values[name] = value
+  const missing = names.filter((n) => !(n in values) || !values[n])
+  if (missing.length) throw Object.assign(new Error(`${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} not in the file any more.`), { status: 400 })
+  return values
+}

package/src/secret-names.js

@@ -0,0 +1,26 @@
+// quilt_secret_names (src/mcp.js, src/relay-mcp.js): a session's secrets as an agent reads them.
+// Names, where each goes, who can use it, and the variables `quilt run` sets: never a value.
+import { LEVEL_WORDS } from './api/secrets-access.js'
+
+export const SECRET_NAMES_DESCRIPTION = "The session's secrets (API keys and the like), by name: each one's level (session, workspace or team), the one host it is sent to, who can use it, whether you can, and the environment variables `quilt run` sets for it. Never a value: nobody can read one back, you included. To use them, run the command that needs them through `quilt run -- <command>` (for example `quilt run -- npm run dev`): the command gets NAME=quilt and NAME's base URL, and its requests go through Quilt's vault, which adds the real key."
+
+export const RUN_GUIDE = 'Run commands that need the session\'s secrets through `quilt run -- <command>`, never with keys pasted into files, chat or .env: the command gets `NAME=quilt` and `<NAME>_BASE_URL` (STRIPE_KEY gives STRIPE_BASE_URL; known SDK variables like OPENAI_BASE_URL and ANTHROPIC_BASE_URL are set too), so point the code\'s base URL at that variable; Quilt\'s vault adds the real key on the way to its one service. `quilt_secret_names` lists the names. Nobody can read a value back, and you never need one.'
+
+const WHO = { agents: 'agents and people', people: 'people only' }
+
+/** The tool's answer for `names` (GET /v1/sessions/:room/secret-names). */
+export function describeSecretNames ({ names = [], kind = 'agent', hosted = false } = {}) {
+  if (hosted) {
+    const head = 'You are a hosted agent: you run no commands, so you can\'t use secrets. A person, or an agent with a computer or a sandbox, runs commands with them through `quilt run`.'
+    if (!names.length) return `${head} This session has no secrets.`
+    return `${head}\n\nThe session's secrets (names only):\n${names.map((n) => `- ${n.name} (${LEVEL_WORDS[n.level] || n.level}) → ${n.upstream}, ${WHO[n.who] || n.who}`).join('\n')}`
+  }
+  if (!names.length) return 'This session has no secrets. People add them in the Quilt app (Session settings → Secrets) or on heyquilt.com for a team; nobody pastes keys into files or chat.'
+  const line = (n) => {
+    const can = n.state === 'ready' ? 'You can use it.'
+      : n.state === 'ask' ? 'Each run asks your person to allow it in the Quilt app (quilt run waits for them).'
+        : `You can't: ${n.why || 'not for you'}.`
+    return `- ${n.name} (${LEVEL_WORDS[n.level] || n.level}) → ${n.upstream}, ${WHO[n.who] || n.who}. ${can} quilt run sets ${n.env.map((v, i) => (i === 0 ? `${v}=quilt` : v)).join(', ')}.`
+  }
+  return `The session's secrets (names only: nobody can read a value back, you included):\n${names.map(line).join('\n')}\n\n${RUN_GUIDE}`
+}

package/src/secret-run.js

@@ -0,0 +1,80 @@
+// `quilt run -- <command>` (docs/superpowers/specs/2026-10-18-secrets.md): starts a command with
+// a stand-in and a gateway address for each secret it may use, never a value. Where it asks:
+// a sandbox's QUILT_AGENT_KEY (the agent), else the session running in this folder (its person,
+// or the agent it runs as), through its control API.
+import { spawn as spawnChild } from 'node:child_process'
+import { runEnv } from './ui/secret-rules.js'
+import { ENV_KEY_NAME } from './ui/agent-env-key.js'
+import { createRun, waitRun, endRun } from './secrets-client.js'
+
+// `quilt git-token` printed a GitHub token, which put it in the terminal and the AI's context.
+export const GIT_TOKEN_GONE = 'quilt git-token no longer prints a token: Quilt never hands a value to a terminal or an AI. git signs in to GitHub through Quilt by itself (its credential helper), so fetch, commit and push as usual; Quilt opens the pull request for your task\'s branch. Keys your project needs go in the session\'s secrets and run through `quilt run -- <command>`.'
+
+export const RUN_USAGE = `usage: quilt run -- <command> [args...]
+
+Runs a command with the session's secrets, without ever giving it a value. For each secret it
+may use, the command gets NAME=quilt and NAME's base URL (STRIPE_KEY gives STRIPE_BASE_URL, and
+known SDK variables like OPENAI_BASE_URL): its requests go to Quilt's vault, which adds the real
+credential and sends them on to that secret's one service. People-only secrets wait for the
+person to allow them in the Quilt app, each run; agents never get them.`
+
+/**
+ * Where run tokens come from: { start(label), wait(id), end(id) } for the session in `dir`
+ * (control API) or the sandbox's key. null when there is neither.
+ */
+export function runSource ({ key, daemon, call }) {
+  if (key) {
+    const c = { api: key.api, token: key.key }
+    return { who: key.name || 'this agent', start: (label) => createRun(c, { room: key.room, label }), wait: (id) => waitRun(c, id), end: (id) => endRun(c, id) }
+  }
+  if (daemon) {
+    return { who: 'you', start: (label) => call(daemon, 'POST', '/secrets/run', { label }), wait: (id) => call(daemon, 'POST', '/secrets/run/wait', { id }), end: (id) => call(daemon, 'POST', '/secrets/run/end', { id }) }
+  }
+  return null
+}
+
+/**
+ * Runs `command` (an argv array) with its secrets' stand-ins: resolves to its exit code.
+ * Says on stderr which names it got and why any were left out; never a value.
+ */
+export async function runWithSecrets ({ command, source, env = process.env, say = (m) => process.stderr.write(`${m}\n`), spawn = spawnChild, waitMs = Number(env.QUILT_RUN_WAIT_MS) || 2 * 60 * 1000, now = Date.now }) {
+  if (!command.length) throw new Error(RUN_USAGE)
+  const label = command.join(' ').slice(0, 200)
+  let started = await source.start(label)
+  let secrets = started.secrets || []
+  const asked = secrets.filter((s) => s.state === 'asked')
+  if (asked.length) {
+    say(`quilt run: waiting for ${source.who === 'you' ? 'you' : 'its person'} to allow ${asked.map((s) => s.name).join(', ')} (people only) in the Quilt app…`)
+    const end = now() + waitMs
+    while (secrets.some((s) => s.state === 'asked') && now() < end) {
+      try { secrets = (await source.wait(started.run.id)).secrets || secrets } catch (err) { say(`quilt run: ${err.message}`); break }
+    }
+  }
+  const ready = secrets.filter((s) => s.state === 'ready')
+  for (const s of secrets) {
+    if (s.state === 'ready') continue
+    say(`quilt run: ${s.name} left out: ${s.state === 'asked' ? 'nobody allowed it in time' : s.why || 'not for this run'}`)
+  }
+  const childEnv = { ...env }
+  // The command is the project's own code: it gets no Quilt key of its own.
+  delete childEnv[ENV_KEY_NAME]
+  if (ready.length) {
+    Object.assign(childEnv, runEnv(ready, { vault: started.vault, token: started.token }))
+    say(`quilt run: ${ready.map((s) => `${s.name} → ${s.upstream}`).join(', ')} (through Quilt's vault; the command never sees a value)`)
+  } else if (!secrets.length) say('quilt run: this session has no secrets yet; running the command as it is')
+  const runId = started.run && started.run.id
+  const code = await new Promise((resolve) => {
+    let child
+    try {
+      child = spawn(command[0], command.slice(1), { stdio: 'inherit', env: childEnv, shell: process.platform === 'win32' })
+    } catch (err) { say(`quilt run: could not start ${command[0]}: ${err.message}`); return resolve(127) }
+    const pass = (sig) => () => { try { child.kill(sig) } catch {} }
+    const onInt = pass('SIGINT'); const onTerm = pass('SIGTERM')
+    process.on('SIGINT', onInt); process.on('SIGTERM', onTerm)
+    child.on('error', (err) => { say(`quilt run: could not start ${command[0]}: ${err.code === 'ENOENT' ? 'no such command' : err.message}`); resolve(127) })
+    child.on('exit', (c, sig) => { process.off('SIGINT', onInt); process.off('SIGTERM', onTerm); resolve(c ?? (sig ? 128 + (sig === 'SIGINT' ? 2 : 15) : 1)) })
+  })
+  // The run token stops working now, not in an hour.
+  if (runId) await source.end(runId).catch(() => {})
+  return code
+}

package/src/secrets-client.js

@@ -0,0 +1,56 @@
+// Secrets on the accounts API (src/api/routes/secrets.js), for the app, the session's control
+// API and `quilt run`. Names, settings and run tokens only: no call here sends or gets a value,
+// except saveSecrets, which sends values to the vault (never to the API) with a write ticket.
+
+async function call ({ api, token, fetch: fetchImpl = globalThis.fetch }, method, route, body, timeoutMs = 30_000) {
+  let res
+  try {
+    res = await fetchImpl(String(api).replace(/\/+$/, '') + route, {
+      method,
+      headers: { ...(body ? { 'content-type': 'application/json' } : {}), ...(token ? { authorization: `Bearer ${token}` } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(timeoutMs)
+    })
+  } catch (err) {
+    throw new Error(`Couldn't reach Quilt (${err.name === 'TimeoutError' ? 'ETIMEDOUT' : err.cause?.code || err.message}).`)
+  }
+  const data = await res.json().catch(() => null)
+  if (!res.ok) throw Object.assign(new Error(data?.error || `Quilt answered ${res.status}.`), { status: res.status })
+  return data || {}
+}
+
+const scopePath = (scope, id) => `/v1/secrets/${encodeURIComponent(scope)}/${encodeURIComponent(id)}`
+
+/** A run token for `quilt run`: { run, token, vault, secrets }. */
+export const createRun = (c, { room, label = '' }) => call(c, 'POST', '/v1/secret-runs', { room, label })
+/** Holds until no secret of the run waits for its person (about 25 s): { run, secrets }. */
+export const waitRun = (c, id) => call(c, 'POST', `/v1/secret-runs/${encodeURIComponent(id)}/wait`, {}, 40_000)
+export const endRun = (c, id) => call(c, 'DELETE', `/v1/secret-runs/${encodeURIComponent(id)}`, null, 5_000)
+/** What the session's secrets come to for this caller: { names: [{ name, level, upstream, who, state, why?, env }] }. */
+export const secretNames = (c, room) => call(c, 'GET', `/v1/sessions/${encodeURIComponent(room)}/secret-names`)
+
+// The app and the website's card.
+export const getSecrets = (c, scope, id) => call(c, 'GET', scopePath(scope, id))
+export const putSecretSettings = (c, scope, id, patch) => call(c, 'PUT', `${scopePath(scope, id)}/settings`, patch)
+export const setSecretWho = (c, scope, id, name, who) => call(c, 'PATCH', `${scopePath(scope, id)}/${encodeURIComponent(name)}`, { who })
+export const deleteSecret = (c, scope, id, name) => call(c, 'DELETE', `${scopePath(scope, id)}/${encodeURIComponent(name)}`)
+export const secretUses = (c, scope, id) => call(c, 'GET', `${scopePath(scope, id)}/uses`)
+export const secretAsks = (c, { wait = false } = {}) => call(c, 'GET', `/v1/me/secret-asks${wait ? '?wait=1' : ''}`, null, 40_000)
+export const answerAsk = (c, runId, allow) => call(c, 'POST', `/v1/me/secret-asks/${encodeURIComponent(runId)}`, { allow: allow === true })
+
+/**
+ * Saves secrets: a write ticket from the API for `entries` ({ name, upstream, format, who }),
+ * then the values straight to the vault with it. Answers { saved: [{ name, digest }] }.
+ */
+export async function saveSecrets (c, scope, id, entries, values) {
+  const t = await call(c, 'POST', `${scopePath(scope, id)}/tickets`, { entries })
+  let res
+  try {
+    res = await (c.fetch || globalThis.fetch)(`${t.vault}/v1/write`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ticket: t.ticket, values }), signal: AbortSignal.timeout(30_000) })
+  } catch (err) {
+    throw new Error(`Couldn't reach Quilt's vault (${err.cause?.code || err.message}).`)
+  }
+  const data = await res.json().catch(() => null)
+  if (!res.ok) throw Object.assign(new Error(data?.error || `The vault answered ${res.status}.`), { status: res.status })
+  return data
+}