perf: cut the app engine's resident memory (about 930 MB to 250-430 MB on a real home)

PERF.md

@@ -785,3 +785,49 @@ The macOS 60 s steady profile fell from 3.03% to 2.10% of a core. What remains
 is the factory's lease reads on runner requests (17%) and the chat presence
 beat (13%). The rig does not follow a live AgentField run, which the live
 round's idle did; the AgentField write above is that path's share.
+
+## Resident memory of the desktop engine
+
+`codeaf app` holds a conversation in memory only while something needs it. The
+method and measurements are in [docs/perf/memory-2026-10-24.md](docs/perf/memory-2026-10-24.md).
+
+- **Members at rest are read, not held.** `tasks.list`, `asks.list` and
+  `processes.list` on a member of an open crew answer from its files when its
+  presence shows no working turn, question, task or process, no service is kept
+  and no stage is lent. `tasks.list` builds the owner-backed list by holding the
+  conversation for the length of one read (at most `appRestReads` = 2 at once),
+  then keeps it under a stamp of the files it was built from: in memory up to
+  `appRestMemoBytes` = 24 MiB (least recently read first; a list larger than
+  that is not kept), and as `<home>/cache/app-tasks/<agent>.json` for the
+  next launch, valid for the same build and the same stamp only. Disk storage
+  keeps at most `appRestDiskTotalBytes` = 96 MiB and `appRestDiskEntries` = 256
+  files, evicting oldest writes first. The inventory is scanned on first use and
+  every `appRestDiskScanEvery` = 1 minute by the idle sweep, which also prunes
+  missing or deleted agents; writes update the inventory without directory scans.
+  Agent deletion removes both entries immediately. Byte-identical settled task
+  checkpoints preserve their identity on open, so snapshot validation can admit
+  conversations with saved tasks. Owner-overlay failures propagate and are
+  never cached; reader completion is deferred and one-shot. Record, rest and
+  project-index admission share the two-second mtime/ctime settling guard.
+  `TestAppReadingAnIdleCrewMemberDoesNotKeepItsConversation` and
+  `TestAppReadsARestingMembersTasksFromTheCacheAfterARelaunch` pin the opens.
+- **A crew member with nothing in flight is let go after `appAgentIdle`** like any
+  other conversation; the crew opens it again for traffic.
+- **Journal records** (`RecordCache`) keep at most `recordCacheEntries` = 8
+  records and drop one not read for `recordCacheIdle` = 30 s. The 256 MiB byte
+  budget and the 16 MiB per-file limit are unchanged.
+- **The project task index** keeps the decoded rows of the last
+  `taskIndexKeptPaths` = 4 indexes of at most `taskIndexKeptBytes` = 4 MiB each.
+- **Plan reads** (`plandb.Store`) reload the plan only when SQLite's
+  `data_version` or the database/log stamp moved.
+  `TestRepeatedReadsOfAnUnchangedPlanLoadItOnce` allows 3 MiB for 200 reads.
+  `TestAppTasksOpensThePlanOnceForAllTheRunRows` allows 16 MiB to list 150 rows.
+- **The collector percent follows the live heap** (`memtrim.go`): the app starts
+  at Go's default percent 100. The governor selects 400 for a small heap, and a
+  larger one is given the percent that
+  lets about `heapHeadroom` = 32 MiB of garbage build up, never below
+  `heapGCMin` = 10. An explicit `GOGC` decides instead. When more than 48 MiB
+  and half of the live heap is held and unused, `debug.FreeOSMemory` runs, at most
+  once a minute. macOS keeps freed pages in a process's resident size until it
+  needs them (`MADV_FREE_REUSABLE`), so `ps` RSS shows the peak of a burst while
+  the footprint (`vmmap --summary`, Activity Monitor) shows what is held.

cmd/codeaf/app.go

@@ -156,6 +156,7 @@ func runApp(args []string) error {
 	defer leaving()
 	defer leave.On(leaving, nil)()
 	guard.Go("app/parent", func() { watchAppParent(ctx, os.Getppid, appParentPoll, leaving) })
+	startHeapTrimmer(ctx)
 	// THE APP'S KEYS LIVE IN THIS PROCESS'S MEMORY, installed before anything
 	// can read a key, and no profile write may put one on disk while they are.
 	defer config.UseAppCredentials(config.NewAppCredentials())()
@@ -606,6 +607,14 @@ type appBackend struct {
 	devices            *appDevices
 	stopSyncedSettings func()
 
+	// restMemo is the task lists of members at rest, so reading them does not
+	// hold their conversations (apprestmemo.go).
+	restMemo  appRestMemo
+	restSlots chan struct{}
+	// waitReaders joins an explicit close's readers; nil waits on their signal.
+	// Tests replace the wait to observe the unlocked admission gate.
+	waitReaders func(<-chan struct{})
+
 	// organizeProposer supplies a naming door when the backend is embedded without held conversations.
 	organizeProposer session.TeamProposer
 
@@ -842,8 +851,13 @@ type appAgent struct {
 	// listening is when this light record began watching crew traffic.
 	listening time.Time
 
-	// gate serializes opening and letting go of this one agent, so two sends
-	// racing for a closed conversation open it once.
+	// readers keeps the held conversation alive until the last disk/owner read
+	// returns. These fields are guarded by b.mu; pinning also holds gate.
+	readers     int
+	readersDone chan struct{}
+	restRead    bool
+	releasing   bool
+	// gate serializes opening, work admission and release for this agent.
 	gate       sync.Mutex
 	nameGate   sync.Mutex // serializes a rename RPC and its view update
 	view       appwire.Agent
@@ -1110,6 +1124,7 @@ func newAppBackend(emit appwire.Emitter, open appOpener) *appBackend {
 			return func() { t.Stop() }
 		},
 		agents:     map[string]*appAgent{},
+		restSlots:  make(chan struct{}, appRestReads),
 		closedDone: make(chan struct{}),
 		sweepStop:  make(chan struct{}),
 		sweepDone:  make(chan struct{}),
@@ -3388,10 +3403,11 @@ func (b *appBackend) workEvent(id string, live *appLive, event session.Event) {
 // started, or is interrupted the moment it is ([appBackend.bootSettle]). No
 // stop waits on the gate an open holds.
 func (b *appBackend) Stop(id string) error {
-	a, err := b.findCrewOwner(id)
+	a, endRead, err := b.findCrewOwner(id)
 	if err != nil {
 		return err
 	}
+	defer endRead()
 	kept := false
 	b.locked(func() {
 		if a.starting {
@@ -3434,6 +3450,7 @@ func (b *appBackend) CloseAgent(id string) error {
 func (b *appBackend) closeAgent(a *appAgent) (view appwire.Agent) {
 	a.gate.Lock()
 	defer a.gate.Unlock()
+	b.lockRelease(a)
 	return b.closeAgentLocked(a)
 }
 
@@ -3454,7 +3471,7 @@ func (b *appBackend) release(a *appAgent) {
 	var id string
 	b.locked(func() {
 		id = a.view.ID
-		live, a.live, a.viewOpen = a.live, nil, false
+		live, a.live, a.viewOpen, a.restRead, a.releasing = a.live, nil, false, false, false
 		if live != nil {
 			a.lastLive = b.now()
 			// Its conversation's open questions go with it, unanswered and
@@ -3469,6 +3486,26 @@ func (b *appBackend) release(a *appAgent) {
 	b.forgetAsksOf(id, live)
 }
 
+func (b *appBackend) releaseIdle(a *appAgent) bool {
+	var live *appLive
+	var id string
+	b.locked(func() {
+		if a.readers > 0 || a.viewOpen || a.live == nil || a.live.running || a.live.compacting {
+			return
+		}
+		id = a.view.ID
+		live, a.live, a.viewOpen, a.restRead, a.crewHeld, a.releasing = a.live, nil, false, false, false, false
+		a.lastLive = b.now()
+		b.dropAsksLocked(a.view.ID, live.asks)
+	})
+	if live == nil {
+		return false
+	}
+	b.finish(live)
+	b.forgetAsksOf(id, live)
+	return true
+}
+
 // finish gives a conversation that is no longer held back, and shuts its
 // outbox once the turn and the lanes have said their last.
 func (b *appBackend) finish(live *appLive) {
@@ -3515,10 +3552,13 @@ func (b *appBackend) finish(live *appLive) {
 // ListAsks answers the agent's open asks. An agent with no conversation held
 // has none this process can answer.
 func (b *appBackend) ListAsks(id string) ([]appwire.Ask, error) {
-	a, err := b.findCrewOwner(id)
+	// A member at rest has no question a held conversation would add: one
+	// waiting on the person says so in its presence and is not at rest.
+	a, endRead, err := b.findCrewReader(id)
 	if err != nil {
 		return nil, err
 	}
+	defer endRead()
 	var asks []appwire.Ask
 	b.locked(func() {
 		if a.live != nil {
@@ -3560,10 +3600,11 @@ func (b *appBackend) answerAskThrough(id, askID, option, text, scope string, sec
 	if handled, err := b.answerCrewAsk(id, askID, option, text, ""); handled {
 		return err
 	}
-	a, err := b.findCrewOwner(id)
+	a, endRead, err := b.findCrewOwner(id)
 	if err != nil {
 		return err
 	}
+	defer endRead()
 	if handled, err := b.answerMoney(a, askID, option, text); handled {
 		return err
 	}
@@ -4532,10 +4573,25 @@ func (b *appBackend) watchSpendRows() (stop func()) {
 // checkpoint does not name — and lays over them what a held conversation has
 // said since.
 func (b *appBackend) ListTasks(id string) ([]appwire.Task, error) {
-	a, err := b.findCrewOwner(id)
+	if a, err := b.find(id); err == nil && b.crewKeeps(id) && !b.isClosing() && !b.tidied(id) && b.memberRests(a) {
+		return b.restingTasks(a, id)
+	}
+	return b.listTasksOf(id)
+}
+
+// listTasksOf is ListTasks for a conversation the crew keeps held when it is
+// busy, and the files' answer otherwise.
+func (b *appBackend) listTasksOf(id string) ([]appwire.Task, error) {
+	a, endRead, err := b.findCrewOwner(id)
 	if err != nil {
 		return nil, err
 	}
+	defer endRead()
+	return b.listTasksHeld(a, id)
+}
+
+// listTasksHeld reads disk and overlays the owner while the caller pins a.
+func (b *appBackend) listTasksHeld(a *appAgent, id string) ([]appwire.Task, error) {
 	var transcript string
 	var fallback time.Time
 	// A quick task is listed by AppQuickTasks, never as a task here (#1880).
@@ -4627,7 +4683,11 @@ func (b *appBackend) ListTasks(id string) ([]appwire.Task, error) {
 			add(appwire.Task{Result: result, ID: appIndexTaskID(id, row.ID), Agent: id, Parent: parent, Title: title, State: state, UpdatedAt: at, YourCall: state == appwire.TaskUnverified})
 		}
 	}
-	for taskID, task := range b.heldTaskViews(a) {
+	owner, err := b.heldTaskViews(a)
+	if err != nil {
+		return nil, err
+	}
+	for taskID, task := range owner {
 		if quickIDs[taskID] {
 			continue
 		}
@@ -4854,6 +4914,7 @@ func (b *appBackend) Close() error {
 func (b *appBackend) letGo(a *appAgent) {
 	a.gate.Lock()
 	defer a.gate.Unlock()
+	b.lockRelease(a)
 	b.release(a)
 }
 
@@ -4863,6 +4924,7 @@ func (b *appBackend) letGoTimed(a *appAgent, w io.Writer) {
 	began := time.Now()
 	a.gate.Lock()
 	defer a.gate.Unlock()
+	b.lockRelease(a)
 	gated := time.Now()
 	var id string
 	b.locked(func() { id = a.view.ID })
@@ -4921,10 +4983,11 @@ func (b *appBackend) sweepOnce() {
 		_, _ = b.SyncStatus()
 	}
 	now := b.now()
+	appRestDisk.maintain(now)
 	var idle []*appAgent
 	b.locked(func() {
 		for _, a := range b.agents {
-			if live := a.live; live != nil && !a.viewOpen && !live.running && now.Sub(live.lastUse) >= appAgentIdle {
+			if live := a.live; live != nil && !a.viewOpen && !live.running && a.readers == 0 && now.Sub(live.lastUse) >= appAgentIdle {
 				idle = append(idle, a)
 			}
 		}
@@ -4945,13 +5008,15 @@ func (b *appBackend) sweepAgent(a *appAgent, now time.Time) {
 	keep := true
 	b.locked(func() {
 		live = a.live
-		keep = live == nil || a.viewOpen || live.running || now.Sub(live.lastUse) < appAgentIdle
+		keep = live == nil || a.viewOpen || live.running || a.readers > 0 || now.Sub(live.lastUse) < appAgentIdle
 	})
-	// A member of an open crew stays held while the crew is open.
-	if !keep && !b.liveNeedsYou(live) && !b.crewKeeps(a.view.ID) && !b.serviceKeeps(a.view.ID) {
+	// A member of an open crew stays held while it has work in flight or a
+	// reason the crew would open it again at once; one with nothing to do goes
+	// like any other, and the crew opens it when traffic comes (applazy.go).
+	if !keep && appLiveWorkSettled(live) && !b.liveNeedsYou(live) && !b.serviceKeeps(a.view.ID) && (!b.crewKeeps(a.view.ID) || b.memberQuiet(a)) {
 		// The state the app reads does not move: the conversation is as
 		// idle on disk as it was in memory.
-		b.release(a)
+		b.releaseIdle(a)
 	}
 }
 

cmd/codeaf/appattention.go

@@ -50,10 +50,11 @@ func (b *appBackend) ShowAsk(agent, id string) (*appwire.Ask, error) {
 }
 
 func (b *appBackend) clockAsk(agent, id string, start bool) (*appwire.Ask, error) {
-	a, err := b.findCrewOwner(agent)
+	a, endRead, err := b.findCrewOwner(agent)
 	if err != nil {
 		return nil, err
 	}
+	defer endRead()
 	live := b.liveOf(a)
 	if live == nil {
 		return nil, appwire.Errorf(appwire.CodeNotFound, "the ask %s is not open", id)
@@ -160,10 +161,11 @@ func (b *appBackend) TaskSince(id, after string) (appwire.Since, error) {
 	if !strings.HasPrefix(after, prefix) {
 		return appwire.Since{}, nil
 	}
-	a, live, err := b.heldLive(agent)
+	a, live, endLive, err := b.borrowLive(agent)
 	if err != nil {
 		return appwire.Since{}, err
 	}
+	defer endLive()
 	journal, ok := live.conn.Conv.(appTaskJournal)
 	if !ok {
 		return appwire.Since{}, nil

cmd/codeaf/appbudget.go

@@ -118,10 +118,11 @@ func (b *appBackend) stampAgentBudget(a *appAgent) appwire.Agent {
 
 // AgentBudget answers agents.budget.get.
 func (b *appBackend) AgentBudget(id string) (appwire.AgentBudget, error) {
-	a, err := b.findCrewOwner(id)
+	a, endRead, err := b.findCrewOwner(id)
 	if err != nil {
 		return appwire.AgentBudget{}, err
 	}
+	defer endRead()
 	return b.budgetOf(id, b.liveOf(a))
 }
 
@@ -132,10 +133,11 @@ func (b *appBackend) SetAgentBudget(set appwire.AgentBudgetSet) (appwire.AgentBu
 	if set.USD != nil && (*set.USD <= 0 || math.IsNaN(*set.USD) || math.IsInf(*set.USD, 0)) {
 		return appwire.AgentBudget{}, appwire.Errorf(appwire.CodeBadParams, "usd must be a positive amount, or null for none")
 	}
-	a, err := b.findCrewOwner(set.ID)
+	a, endRead, err := b.findCrewOwner(set.ID)
 	if err != nil {
 		return appwire.AgentBudget{}, err
 	}
+	defer endRead()
 	if b.isClosing() {
 		return appwire.AgentBudget{}, appwire.Errorf(appwire.CodeClosed, "codeaf is shutting down")
 	}

cmd/codeaf/appclose.go

@@ -844,7 +844,7 @@ func appTaskWasInterrupted(p session.SessionPresence, fresh bool, id string, sta
 
 // heldTaskViews reads after the disk so a start arriving during the listing
 // wins. Locally owned tasks come from the engine, even ahead of its event lane.
-func (b *appBackend) heldTaskViews(a *appAgent) map[string]appwire.Task {
+func (b *appBackend) heldTaskViews(a *appAgent) (map[string]appwire.Task, error) {
 	heard := map[string]appwire.Task{}
 	var live *appLive
 	var id string
@@ -859,15 +859,17 @@ func (b *appBackend) heldTaskViews(a *appAgent) map[string]appwire.Task {
 	// A lent stage lives in this process too, and may have parked a card before the
 	// hold began, when no event could carry it here.
 	if live != nil && (live.conn.Assembled || live.conn.Lent) {
-		if tasks, err := live.conn.Conv.AppTasks(); err == nil {
-			for _, view := range tasks {
-				task := appTaskOfView(id, view)
-				task.UpdatedAt = heard[task.ID].UpdatedAt
-				heard[task.ID] = task
-			}
+		tasks, err := live.conn.Conv.AppTasks()
+		if err != nil {
+			return nil, err
+		}
+		for _, view := range tasks {
+			task := appTaskOfView(id, view)
+			task.UpdatedAt = heard[task.ID].UpdatedAt
+			heard[task.ID] = task
 		}
 	}
-	return heard
+	return heard, nil
 }
 
 // Deleted journals keep their directory for deliverables. Only their lifetime

cmd/codeaf/appcompaction.go

@@ -217,10 +217,11 @@ func appReadPasses(stop <-chan struct{}, passes <-chan session.Event, take func(
 // compaction.ended; the pass's own events reach the page through the
 // connection's pass lane ([appBackend.watchPasses]), ahead of that answer.
 func (b *appBackend) CompactAgent(id string) error {
-	a, live, err := b.heldLive(id)
+	a, live, endLive, err := b.borrowLive(id)
 	if err != nil {
 		return err
 	}
+	defer endLive()
 	conv, ok := live.conn.Conv.(appCompactConv)
 	if !ok {
 		return appwire.Errorf(appwire.CodeUnknownMethod, "this conversation cannot be compacted from here")
@@ -240,7 +241,9 @@ func (b *appBackend) CompactAgent(id string) error {
 		b.locked(func() { live.compacting = false })
 		return appwire.Errorf(appwire.CodeBusy, "too many compactions are running; ask again in a moment")
 	}
+	endWorker := b.pinReaderGated(a)
 	guard.Go("app/compact", func() {
+		defer endWorker()
 		defer func() {
 			<-appCompactSlots
 			b.locked(func() { live.compacting = false })