aegis-desktop 0.8.5 → 0.8.6

package/README.md

@@ -1,6 +1,6 @@
 # AEGIS Desktop
 
-![AEGIS Desktop running: the three-class model picker, an agent turn, a gated tool-approval diff, and the unattended work queue](https://raw.githubusercontent.com/aegisinfo/aegiscode-plugin/main/desktop/docs/demo.gif)
+![AEGIS Desktop running: the three-class model picker, an agent turn, a gated tool-approval diff, and the unattended work queue](docs/demo.gif)
 
 A standalone Electron chat app over the [AEGIS](https://aegiscloud.org) API,
 with an **agentic tool loop**: the model can read, write, and edit files,
@@ -9,9 +9,8 @@ delegate whole sub-tasks to subagents. It does **not** require Claude Code.
 
 ## Install
 
-Download a build from the
-[releases page](https://github.com/aegisinfo/aegiscode-plugin/releases) — the
-repo the release workflow publishes binaries to — or install from npm:
+Prebuilt binaries (AppImage / MSI+NSIS / dmg) ship with each release, and the
+package is on npm:
 
 ```bash
 npm install -g aegis-desktop     # requires Node 18+
@@ -114,16 +113,16 @@ stub and refuse to publish an asset that fails their assertions.
 
 **The model-class picker** — all three routes, switchable mid-conversation:
 
-![The model-class picker listing Aegis Cloud, Bring your own key, and Local](https://raw.githubusercontent.com/aegisinfo/aegiscode-plugin/main/docs/marketing-assets/01-model-class-picker.png)
+![The model-class picker listing Aegis Cloud, Bring your own key, and Local](docs/marketing-assets/01-model-class-picker.png)
 
 **A completed answer** in the transcript:
 
-![A completed answer in the transcript](https://raw.githubusercontent.com/aegisinfo/aegiscode-plugin/main/docs/marketing-assets/02-answer-complete.png)
+![A completed answer in the transcript](docs/marketing-assets/02-answer-complete.png)
 
 **The tool-call approval card** with a proposed edit — what blocks `exec`,
 `writeFile` and `editFile` until you allow, allow for the session, or deny:
 
-![The tool-call approval card with a proposed edit](https://raw.githubusercontent.com/aegisinfo/aegiscode-plugin/main/docs/marketing-assets/03-tool-approval-diff.png)
+![The tool-call approval card with a proposed edit](docs/marketing-assets/03-tool-approval-diff.png)
 
 ## Tools available to the model
 
@@ -156,7 +155,7 @@ aegiscode autonomous add "fix the flaky retry test" --cwd ~/repo --commit
 aegiscode autonomous list
 aegiscode autonomous run                 # drain one task, then stop
 aegiscode autonomous proceed --max 3     # drain up to three
-aegiscode autonomous reconcile --auto    # queue the next unfinished PLAN.md phase, then drain it
+aegiscode autonomous reconcile --auto    # queue the next unfinished phase of your plan file, then drain it
 aegiscode autonomous retry <id>          # put a finished task back
 aegiscode autonomous clear --all         # empty the queue
 ```
@@ -278,17 +277,12 @@ The app registers an `aegis://` protocol handler:
 
 ## Run from source
 
-```bash
-git clone https://github.com/aegiscloud/aegiscode-desktop.git
-cd aegiscode-desktop
-npm install
-npm start
-```
-
-Or, from the monorepo checkout, run this directory directly:
+A source checkout is available to contributors with repository access only — the
+desktop host is not a public repository. From the checkout, run this directory
+directly:
 
 ```bash
-cd aegiscode-plugin/desktop
+cd desktop
 npm install
 npm start
 ```
@@ -328,11 +322,7 @@ transport over the same AEGIS backend — see the repo root for that fuller
 architecture picture, and [cli/README.md](../cli/README.md) for the terminal
 host over the same engine.
 
-**Two repos, one product.** This directory is the source of truth. The
-standalone repo at
-[aegiscloud/aegiscode-desktop](https://github.com/aegiscloud/aegiscode-desktop)
-is a `git subtree split` of it — same code, published separately so it can be
-cloned and built on its own. Edits land here and are synced out; nothing is
-authored there. The npm package
-[`aegis-desktop`](https://www.npmjs.com/package/aegis-desktop) is built from
-that standalone repo.
+**One source of truth.** This directory is it. The npm package
+[`aegis-desktop`](https://www.npmjs.com/package/aegis-desktop) is built from a
+`git subtree split` of it — same code, published without the rest of the
+monorepo. Edits land here and are synced out; nothing is authored elsewhere.

package/lib/avatar/companion.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * companion.js — the four companion behaviours (PLAN Phase 23, spec §4).
+ * companion.js — the four companion behaviours.
  *
  * The behaviours are the morning brief, the idea log, the session reflection
  * and in-session recall. What they have in common is not their content, it is
@@ -42,7 +42,7 @@
  * checkable: nothing here may be a shell, a network call or anything that sends
  * data off the device, and `carveOuts()` is the assertion that says so.
  *
- * Pure: no `fs`, no Electron, no globals. See `docs/avatar-plan.md` §2 and §4.
+ * Pure: no `fs`, no Electron, no globals.
  */
 
 const level = require('./level.js');

package/lib/avatar/cosmetics.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * cosmetics.js — the cosmetics pack format and its validator (Phase 24).
+ * cosmetics.js — the cosmetics pack format and its validator.
  *
  * WHY A FORMAT AT ALL. Spec §3 says the avatar is *data, not art*: a persona is
  * one JSON record and a look is a layered SVG assembled from a part manifest, so
@@ -196,7 +196,7 @@ function validatePack(raw) {
   for (const where of forbidden) {
     errors.push(
       `cosmetics packs may not carry \`${where}\` — a pack sells LOOKS only, never XP, ` +
-        'levels, recall breadth, approval friction or personalization (docs/avatar-plan.md §3)',
+        'levels, recall breadth, approval friction or personalization',
     );
   }
 

package/lib/avatar/events.js

@@ -17,7 +17,7 @@
  *    that throws on an unrecognised signal turns every future feature into a
  *    crash in the avatar, so the default transition is "stay put".
  *
- * The states are the ones `docs/avatar-plan.md` §4 lists, wired to signals that
+ * The states are wired to signals that
  * already exist: turn start/stream/end, `tool.*` from the tool host, the
  * approval card, queue progress, and sync status. No new event bus.
  *
@@ -175,7 +175,7 @@ const TABLE = Object.freeze({
 
 /**
  * Expression id per state. The renderer maps these to the persona's expression
- * pack; keeping the mapping here means Phase 22 needs no state knowledge.
+ * pack; keeping the mapping here means the renderer needs no state knowledge.
  */
 const EXPRESSIONS = Object.freeze({
   idle: 'neutral',

package/lib/avatar/holder-turn.js

@@ -1,13 +1,12 @@
 'use strict';
 
 /**
- * holder-turn.js — the seam where a holder reaches turn assembly (PLAN Phase 28;
- * docs/avatar-identity-plan.md §3, §4, §7).
+ * holder-turn.js — the seam where a holder reaches turn assembly.
  *
  * `register.js` turns a persona into a bounded tone fragment, `profile.js` folds
  * a holder's memory into evidence-gated facets, and `holders.js` owns the
  * directory and the isolation filter. This file is the only place they meet, and
- * it is where the one claim Phase 28 is really about gets decided:
+ * it is where the one claim this file is really about gets decided:
  *
  *   **Holder A's assembled prompt cannot contain holder B's text.**
  *
@@ -22,10 +21,10 @@
  *  - *The recall block.* The same filter runs on the recall rows, so an entry
  *    that arrives after the wrong cache still cannot be quoted into A's turn.
  *
- * The Phase 28 test drives both through `assemble()` — the function main.js
+ * The test drives both through `assemble()` — the function main.js
  * actually calls — and then through `engine.js` with this file's prompt builder
  * injected, grepping the system prompt a scripted transport received. That is
- * the Phase 18 lesson (never assert on a harness leg that was re-pointed) turned
+ * the lesson (never assert on a harness leg that was re-pointed) turned
  * on privacy: the interesting failure is a filter applied after the wrong cache,
  * and only the real path can show it.
  *
@@ -157,7 +156,7 @@ function profileFragment(fold, opts = {}) {
  * rows. Exported because main.js renders it into the memory pane as well, and
  * one implementation is one thing to get right.
  *
- * `opts.header` exists for the one caller that has no holder: Phase 20's turn
+ * `opts.header` exists for the one caller that has no holder: the account-level turn
  * assembly recalls the account's memory before any holder exists, and captioning
  * that block "this holder's memory" would be a lie told in the prompt. The
  * default stays the holder header, so every holder-scoped caller is unchanged.
@@ -253,7 +252,7 @@ function assemble(input = {}) {
     entryIds: scoped.map((row) => String(row && row.id)).filter(Boolean),
     recallIds: recall.entryIds,
     // Rows the recall block could not fit. Facet drops have their own field, so
-    // neither the usage accounting nor the Phase 28 assertions have to guess
+    // neither the usage accounting nor the assertions have to guess
     // which kind of "dropped" this is.
     dropped: recall.dropped,
     neutralizations: profile.neutralizations + recall.neutralizations + registerFragment.neutralizations,

package/lib/avatar/holders.js

@@ -1,11 +1,10 @@
 'use strict';
 
 /**
- * holders.js — who holds the memory (PLAN Phase 28; docs/avatar-identity-plan.md
- * §3, §4, §5).
+ * holders.js — who holds the memory.
  *
- * `identity.js` (Phase 25) decides *which* holder a set of signals points at and
- * refuses to merge two people on a fingerprint match. `profile.js` (Phase 25)
+ * `identity.js` decides *which* holder a set of signals points at and
+ * refuses to merge two people on a fingerprint match. `profile.js`
  * folds one holder's entries into bounded, evidence-gated facets. Neither of
  * them owns a directory. This file is that owner — the layout, the registry, the
  * switch, the conflict decision and the "why does it know this" surface — and it
@@ -32,7 +31,7 @@
  *     is the client-side filter §3 calls "the assertion that the fix happened":
  *     the server-side scope is the fix, and this is what proves it ran. It is
  *     used by the fold *and* by the recall block, so a leak needs to defeat one
- *     function rather than two call sites — and the Phase 28 test drives two
+ *     function rather than two call sites — and the test drives two
  *     holders through the real turn assembly and greps the prompt.
  *
  *  4. **Every claim is traceable and deletable.** `provenance()` renders a
@@ -63,7 +62,7 @@ const PROFILE_FILE = 'profile.json';
 const FORGOTTEN_FILE = 'forgotten.json';
 
 /**
- * The one thing a switch may leave behind. A list, not a sentence: the Phase 28
+ * The one thing a switch may leave behind. A list, not a sentence: the
  * test iterates it, so adding a survivor to the code without adding it here
  * makes the test fail rather than the promise quietly rot.
  */
@@ -445,7 +444,7 @@ function applyConflict(registry, resolution, choice = {}) {
  * particular and therefore to the holder asking, which is what makes a legacy
  * unstamped ledger readable instead of invisible.
  *
- * `clientFilter:false` exists only so the Phase 28 isolation test can prove the
+ * `clientFilter:false` exists only so the isolation test can prove the
  * filter is load-bearing by removing it and watching the leg go red. It is not
  * reachable from any IPC handler (holder-ipc.js never passes it).
  */

package/lib/avatar/identity.js

@@ -3,7 +3,7 @@
 /**
  * identity.js — whose memory it is.
  *
- * `docs/avatar-plan.md` made memory the value; value is meaningless
+ * Memory is the value; value is meaningless
  * unattributed. This module answers exactly one question — *which holder is at
  * the keyboard* — from signals the caller already has, and it answers with a
  * **proposal plus provenance**, never with a merge.
@@ -38,7 +38,7 @@
  *  4. **Resolution is pure and never writes.** `holders.json` is validated,
  *     repaired and copied; the input registry is never mutated, and the fields
  *     `proposal`/`conflict`/`needsMint` exist precisely so main writes the file
- *     with the user's confirmation (Phase 26) instead of this module guessing.
+ *     with the user's confirmation instead of this module guessing.
  *
  * Pure: no fs, no Electron, no crypto import — the caller supplies `hash` so
  * this file is testable in plain Node exactly like `lib/sync/*`.
@@ -149,10 +149,10 @@ function looksLikeRawKey(value) {
  *
  * Deterministic on purpose — the same machine seed produces the same id on a
  * reinstall, which is what keeps "the ledger survives a reinstall"
- * (`avatar-plan.md` §1.5) true for an install that never had a cloud key.
+ * true for an install that never had a cloud key.
  *
  * @returns {string|null} `null` when there is nothing trustworthy to mint from;
- *   the caller then falls back to random bytes (main, Phase 26).
+ *   the caller then falls back to random bytes.
  */
 function mintHolderId(hash, seed) {
   if (typeof hash !== 'function') return null;
@@ -424,7 +424,7 @@ function setActive(current, id) {
   return validate(base);
 }
 
-/** Phase 29 «forget»: drop one row, and re-point `active` if it was that row. */
+/** «forget»: drop one row, and re-point `active` if it was that row. */
 function removeHolder(current, id) {
   const base = validate(current).registry;
   const wanted = holderIdShape(id);
@@ -475,7 +475,7 @@ const CONFIDENCE = Object.freeze({
  *   `conflict.a` is what you would be switching away from (the registry's
  *   active holder, or the losing signal's holder) and `conflict.b` is the
  *   proposal. Returned so main can show a "who is at the keyboard?" card
- *   (Phase 28) instead of switching silently.
+ *   instead of switching silently.
  */
 function resolve(signals, registry) {
   const raw = signals && typeof signals === 'object' ? signals : {};
@@ -519,7 +519,7 @@ function resolve(signals, registry) {
     // A fingerprint that matches no registry row proves nothing about who this
     // is, so it can never *select* a holder. It can only be proposed for
     // binding onto the holder that WAS resolved, which main writes only after
-    // the user confirms (Phase 26) — this module never writes anything. Built
+    // the user confirms — this module never writes anything. Built
     // here rather than in the last rung so every rung reports it identically:
     // an explicit persona import with a freshly rotated key is the same
     // question as a fresh install with one.

package/lib/avatar/level.js

@@ -31,7 +31,7 @@
  *     they too cannot widen write/shell/network approval.
  *
  * Pure: no fs, no Electron, no process access except the `env` the caller
- * passes. See `docs/avatar-plan.md` §2.
+ * passes.
  */
 
 const { TIERS, tierFor, tierIndex } = require('./tiers.js');

package/lib/avatar/mirror.js

@@ -1,11 +1,10 @@
 'use strict';
 
 /**
- * mirror.js — the per-holder cloud mirror (PLAN Phase 29;
- * docs/avatar-identity-plan.md §6, extending docs/avatar-plan.md §1.5).
+ * mirror.js — the per-holder cloud mirror.
  *
- * Phase 20 put the ledger on disk, Phase 25 made a profile foldable from it and
- * Phase 28 gave every row a holder. All three are local. This file is the half
+ * Earlier work put the ledger on disk, made a profile foldable from it and
+ * gave every row a holder. All three are local. This file is the half
  * that leaves the machine, and it exists to make four claims true — each of
  * which is a test in `desktop/test/avatar-mirror.test.mjs`, not a paragraph:
  *
@@ -22,8 +21,8 @@
  *     `reconcile()` unions two sides by a content-addressed row id, deduplicates
  *     a row both machines already have, and sorts by `(t, id)`. Two machines
  *     that appended in opposite orders converge on the *same bytes*, and
- *     `derive()`'s order independence (docs/avatar-plan.md §1) makes that the
- *     same level. The Phase 29 ordering test feeds both interleavings and
+ *     `derive()`'s order independence makes that the
+ *     same level. The ordering test feeds both interleavings and
  *     asserts one level; the idempotence leg asserts feeding the union back in
  *     cannot double a level, which is what would actually hurt.
  *
@@ -337,7 +336,7 @@ function readMirror(memoryRows, holderId) {
  * trusted as a conclusion — `payload.profile`/`payload.facets` are dropped
  * explicitly and recorded in `refused`. The fold itself is `profile.fold()`
  * with `holder` supplied, so a facet can only cite an entry id that survived
- * the holder filter (Phase 25's pure-seam isolation) *and* exists in this
+ * the holder filter *and* exists in this
  * input (the `citable` set inside the fold).
  */
 function refold(input = {}) {

package/lib/avatar/packs/README.md

@@ -23,7 +23,7 @@ paid.
 ## The rule this directory exists to enforce
 
 **Cosmetics only.** Never XP, levels, recall breadth, approval friction or
-personalization (`docs/avatar-plan.md` §3, invariant 8). `validatePack` refuses a
+personalization. `validatePack` refuses a
 pack carrying `xp`, `level`, `recallEntries`, `approvals`, `toolGrants`,
 `modelFloor`, `proactivity`, `price`, `entitlement`, … at any depth, and refuses
 a `tier` that contradicts the unlock table — so a "paid pack that also widens a

package/lib/avatar/persona.js

@@ -7,7 +7,7 @@
  * that is a settings pane with hand-written branches for every option, which
  * makes a new outfit a code change and a commissioned art pack a fork. The way
  * this module does it: a persona is one JSON record, validated and coerced
- * here, and Phase 22's renderer assembles layered SVG from a part manifest. A
+ * here, and the renderer assembles layered SVG from a part manifest. A
  * theme is then a file. Zero code changes.
  *
  * Validation is REPAIR-ORIENTED, not reject-oriented, with exactly two hard
@@ -23,20 +23,20 @@
  * it is the user's own file.
  *
  * The one place that IS adversarial is the `register` block and the identity
- * strings, because they end up in the system prompt (Phase 21). Those are
+ * strings, because they end up in the system prompt. Those are
  * sanitized here at the storage boundary — control characters and newlines are
  * stripped so a name cannot break out of its line — and the *prompt* fragment
  * is additionally bounded and neutralized in `register.js`. Two layers, because
  * a name is user-authored text going into a prompt.
  *
- * Pure: no fs, no Electron. Phase 21's main process reads/writes the file.
+ * Pure: no fs, no Electron. The main process reads/writes the file.
  */
 
 /** Bump when the record shape changes; `migrate` walks old records forward. */
 const SCHEMA_VERSION = 1;
 
 /**
- * The part manifest. Ids only — geometry lives in `renderer/avatar/` (Phase 22),
+ * The part manifest. Ids only — geometry lives in `renderer/avatar/`,
  * which reads these same ids. Validation is against THIS list so a typo in a
  * hand-edited persona is caught at load rather than rendering an empty head.
  */
@@ -82,7 +82,7 @@ function has(list, value) {
 
 /**
  * Collapse whitespace and strip control characters. A name is a single line of
- * text in a UI, and (Phase 21) a single line in a prompt — so newlines, tabs and
+ * text in a UI, and a single line in a prompt — so newlines, tabs and
  * the unicode line separators are removed rather than escaped.
  */
 function cleanText(value, max) {

package/lib/avatar/profile.js

@@ -1,8 +1,7 @@
 'use strict';
 
 /**
- * profile.js — what *this holder's* memory is allowed to personalise (Phase 25,
- * identity plan §4).
+ * profile.js — what *this holder's* memory is allowed to personalise.
  *
  * `identity.js` answers "whose memory is it"; this module answers the question
  * that follows immediately: given that holder's own rows, what may the avatar
@@ -36,21 +35,21 @@
  *     Absence of evidence produces no facet: never "probably prefers terse
  *     answers".
  *  4. COLD START IS NEUTRAL. No evidence ⇒ `coldStart: true`, `facets: []`,
- *     `budget.used: 0`. Phase 27 renders that as an empty fragment, i.e. an
+ *     `budget.used: 0`. The renderer shows that as an empty fragment, i.e. an
  *     avatar that behaves exactly like an unconfigured install. It does not
- *     guess a personality, the same honesty rule as `avatar-plan.md` §1.4.
+ *     guess a personality.
  *  5. DETERMINISTIC. No clock (`now` is an argument), no randomness, no map
  *     iteration order leaking into output: facets are ordered by
  *     `(confidence desc, lastSeen desc, id asc)` and, for two facets of the
  *     same class on the same day, `key asc` — one extra term so the order is
  *     total and a permutation of the input cannot change the output bytes.
- *  6. BOUNDED. The assembled facets are capped at `BUDGET_TOKENS` (900, per
- *     §Phase 27), dropped whole, lowest priority first — never sliced
+ *  6. BOUNDED. The assembled facets are capped at `BUDGET_TOKENS` (900),
+ *     dropped whole, lowest priority first — never sliced
  *     mid-sentence, which is the failure mode a naive `slice()` produces.
  *
  * Pure: no fs, no Electron, no clock, no crypto. It reuses `persona.cleanText`
  * (the storage boundary's sanitizer) and `register.estimateTokens` (the same
- * 4-chars-per-token ceiling Phase 21 uses) so the two prompt fragments Phase 27
+ * 4-chars-per-token ceiling used elsewhere) so the two prompt fragments the renderer
  * concatenates are measured with one ruler.
  */
 
@@ -73,7 +72,7 @@ const FACET_IDS = Object.freeze([
   'toneCalibration',
 ]);
 
-/** §Phase 27: the profile fragment's ceiling. */
+/** The profile fragment's ceiling. */
 const BUDGET_TOKENS = 900;
 
 /** Longest a single facet `value` may be (it is UI text and prompt text). */
@@ -360,7 +359,7 @@ function orderFacets(facets) {
 /**
  * Take facets in priority order while they fit. Whole facets only: a fragment
  * that ends mid-sentence reads as a truncated thought, which is worse than a
- * shorter one, and §Phase 27 asserts exactly this.
+ * shorter one, and the test asserts exactly this.
  */
 function applyBudget(ordered, limit = BUDGET_TOKENS) {
   const kept = [];
@@ -384,12 +383,12 @@ function applyBudget(ordered, limit = BUDGET_TOKENS) {
 /**
  * Does this row belong to the holder being folded?
  *
- * Unstamped rows belong to whoever is asking: they predate Phase 26's stamping
+ * Unstamped rows belong to whoever is asking: they predate the stamping
  * and the alternative — dropping them — would silently empty the profile of
  * every existing install. A row stamped for *someone else* is never folded, and
  * that is the pure-seam half of §3's "isolation is the load-bearing property":
  * `sources` built downstream can only cite ids that survived this filter. The
- * real-seam half (Phase 28) asserts it again through actual turn assembly,
+ * real-seam half asserts it again through actual turn assembly,
  * because a filter applied after the wrong cache is exactly the bug a
  * pure-function test misses.
  */
@@ -844,9 +843,9 @@ if (Object.keys(FOLDERS).length !== FACET_IDS.length || FACET_IDS.some((id) => t
  * @param {object} input
  * @param {string} [input.holder]      the holder these rows belong to. Supplying
  *   it is how a caller states *whose* memory this is: rows stamped for another
- *   holder are dropped here and can therefore never be cited by a facet. Phase
- *   26 always passes it (the registry's `active`); omitting it means "the caller
- *   already scoped this input", which is why Phase 28 asserts the same property
+ *   holder are dropped here and can therefore never be cited by a facet. The
+ *   caller always passes it (the registry's `active`); omitting it means "the caller
+ *   already scoped this input", which is why the test asserts the same property
  *   again at the real turn-assembly seam.
  * @param {Array} [input.entries]      memory entries for this holder, aegis1's
  *   row shape: `{ id, content, role, tags: [], session, createdAt, … }`.

package/lib/avatar/register.js

@@ -2,7 +2,7 @@
 
 /**
  * register.js — the persona's register turned into ONE bounded system-prompt
- * fragment (Phase 21; shared by Phase 27's profile fragment).
+ * fragment.
  *
  * `persona.js` is the storage boundary: it sanitizes identity/register text on
  * the way to disk. This is the SECOND layer, and the one that matters at the
@@ -38,7 +38,7 @@
 
 const personaModule = require('./persona.js');
 
-/** ~300 tokens, per docs/avatar-plan.md §3. */
+/** ~300 tokens. */
 const MAX_FRAGMENT_TOKENS = 300;
 
 /**

package/lib/avatar/store.js

@@ -1,9 +1,9 @@
 'use strict';
 
 /**
- * store.js — the main process's half of level authority (Phase 20).
+ * store.js — the main process's half of level authority.
  *
- * Phase 19 shipped the avatar core as five pure modules with no IO at all:
+ * The avatar core shipped as five pure modules with no IO at all:
  * `xp.js` knows what an event is worth and how a ledger replays into a level,
  * `level.js` knows what a level buys, but neither can read a file or a clock.
  * This file is the missing half and it deliberately owns *only* the two things
@@ -51,11 +51,11 @@ const personaModule = require('./persona.js');
 const LEDGER_DIR = 'avatar';
 const LEDGER_FILE = 'ledger.jsonl';
 /**
- * `<userData>/avatar/persona.json` — the persona DOCUMENT (Phase 21).
+ * `<userData>/avatar/persona.json` — the persona DOCUMENT.
  *
  * It lives here, next to the ledger and not in settings.json, because a persona
  * is a document rather than a preference: it is imported, exported, hand-edited
- * and eventually synced per holder (Phase 26), and every one of those paths
+ * and eventually synced per holder, and every one of those paths
  * wants validation on the way in. The `__avatar` settings namespace holds only
  * the three switches (lib/settings.js), so a renderer can never write a persona
  * through the settings surface.
@@ -206,7 +206,7 @@ function createAvatarStore({ dir, now = () => Date.now(), env = process.env, log
    *
    * `award()` above is the internal path: its callers are hooks that already
    * know which kind they are recording. This is the externally reachable one
-   * (Phase 21's `aegis:avatarAward`), so it is the one that must not be a
+   * (`aegis:avatarAward`), so it is the one that must not be a
    * generic "write a line into the ledger" bridge: an unknown kind is refused
    * with a reason rather than written as a zero-XP line, which keeps the ledger
    * a record of priced events only. `xp` is never accepted from the caller —
@@ -226,7 +226,7 @@ function createAvatarStore({ dir, now = () => Date.now(), env = process.env, log
     return { ok: true, kind: name, xp: xp.xpFor(name), entry };
   }
 
-  // --- persona document (Phase 21) ----------------------------------------
+  // --- persona document ----------------------------------------
   // The persona is read and written ONLY here, by main. Both directions run
   // through persona.js validation, so a hand-edited or imported file is
   // repaired with warnings rather than trusted, and the identity/register text

package/lib/avatar/transfer.js

@@ -1,8 +1,7 @@
 'use strict';
 
 /**
- * transfer.js — persona export, persona import and per-holder forget
- * (PLAN Phase 29; docs/avatar-identity-plan.md §5 and §7.3).
+ * transfer.js — persona export, persona import and per-holder forget.
  *
  * A persona is taste. Memory is not. This file exists to keep those two apart
  * across the one boundary where they would otherwise merge — moving a persona

package/lib/avatar/turn.js

@@ -1,9 +1,9 @@
 'use strict';
 
 /**
- * turn.js — the ONE seam where a level reaches turn assembly (Phase 20) and
+ * turn.js — the ONE seam where a level reaches turn assembly and
  * where the persona's register fragment is attached to the engine's system
- * prompt (Phase 21).
+ * prompt.
  *
  * `level.js` says what a level buys and `register.js` says what the persona's
  * tone is; neither of them knows what a turn is. This file is the only place
@@ -23,7 +23,7 @@
  *    level that silently starts spending per turn is a billing surprise.
  *  - No approval, grant or tool field is produced here. Turn assembly reads a
  *    recall policy; it is structurally incapable of reading a widened
- *    permission out of it, which is what makes the Phase 20 carve-out test a
+ *    permission out of it, which is what makes the carve-out test a
  *    statement about the code rather than a promise about the developers.
  *  - `applyModelFloor(model, policy)` turns the L20 floor into the model this
  *    turn actually travels on. It is a ROUTING constraint and nothing more: it
@@ -101,7 +101,7 @@ function recallPolicy(caps, opts = {}) {
  * Ids that reason on their own, as this build can tell without a round trip:
  *
  *  - DeepSeek's reasoning family — the same anchored set `engine.js` sizes its
- *    budget from (DEEPSEEK_REASONING_MODEL_RE, mirrored from aegiscodex-dev),
+ *    budget from (DEEPSEEK_REASONING_MODEL_RE, mirrored from the upstream engine),
  *    because a model whose hidden chain-of-thought bills against its own output
  *    budget is by definition a model that reasons.
  *  - the pooled brain tier (`nexus-brain` and the `-smart`/`-neo` spellings the

package/lib/local/agents.js

@@ -2,7 +2,7 @@
 
 /**
  * agents.js — subagent prompt presets for the desktop `task` tool, ported
- * from aegiscodex-dev's src/agents.js (same roles, same synthesis presets).
+ * from the upstream engine reference (same roles, same synthesis presets).
  * A preset is a system prompt: `task` runs it through the normal engine.chat
  * loop as a nested turn (its own tool rounds, same model class), not a
  * separate runtime, so the presets are pure prompt composition.

package/lib/local/autonomous.js

@@ -311,7 +311,7 @@ function resolveEffort({ effort, env, fanout } = {}) {
 
 /**
  * The operating directive injected as the autonomous turn's prompt preamble.
- * Ported verbatim in spirit from aegiscodex-dev/src/autonomous.js so both
+ * Ported verbatim in spirit from the upstream engine reference so both
  * clients behave the same; duplicated rather than vendored because the plugin
  * hosts no ESM build of that module.
  */

package/lib/local/engine.js

@@ -8,7 +8,7 @@
  * chosen class is the user's explicit selection.
  *
  * Since the tool-calling port it ALSO owns the agent loop (the client half of
- * aegiscodex-dev's src/backend.js runProvider): every turn carries a real
+ * the upstream engine's src/backend.js runProvider): every turn carries a real
  * system prompt (prompt.js) and the builtin tool schemas (tools.js), and when
  * a provider answers with tool calls the loop executes them in-process and
  * feeds the results back for as many rounds as the model keeps calling tools
@@ -27,7 +27,7 @@
  * executor never has to be exposed to the renderer.
  *
  * Two turn-scoped resources ride along with the loop, mirroring
- * aegiscodex-dev's runProvider exactly:
+ * the upstream engine's runProvider exactly:
  *   - a lazily-started ShellSession (shell.js) that the `exec` tool shares,
  *     so cd/export state persists across calls within one turn instead of
  *     each call spawning a fresh process;
@@ -159,7 +159,7 @@ function providerKeyFromEnv(provider) {
 }
 
 /**
- * Mirrors aegiscodex-dev's src/backend.js DEEPSEEK_REASONING_MODEL_RE +
+ * Mirrors the upstream engine's src/backend.js DEEPSEEK_REASONING_MODEL_RE +
  * EFFORT_TOKEN_BUDGET verbatim. DeepSeek's reasoning models (deepseek-flash,
  * i.e. "Flash 4.1", deepseek-v4-pro, the deprecated deepseek-reasoner, and the
  * legacy v4-flash/v4.1-flash aliases some configs still carry) spend part of
@@ -170,7 +170,7 @@ function providerKeyFromEnv(provider) {
  * tool calls, just a turn that "completes" with nothing to show for it (the
  * empty-response bug). A user pointing the Custom OpenAI-compatible class
  * straight at DeepSeek's API hits exactly this, so the request is sized by the
- * same effort budget aegiscodex-dev uses for its own direct DeepSeek calls.
+ * same effort budget the upstream engine uses for its own direct DeepSeek calls.
  *
  * desktop/renderer/budget.js carries the renderer's copy of these two
  * constants plus budgetFor() below; test/budget.test.mjs requires both and
@@ -437,7 +437,7 @@ function createLocalEngine({
   settings,
   tools,
   promptBuilder,
-  // Phase 20 — the level's recall breadth, injected by the host that owns the
+  // The level's recall breadth, injected by the host that owns the
   // avatar ledger (desktop/main.js builds one from lib/avatar/turn.js). It is a
   // SEAM rather than a call into lib/avatar/* because this engine is shared with
   // the CLI (cli/src/deps.js loads this file): the engine must not grow a
@@ -920,7 +920,7 @@ function createLocalEngine({
         // that used to claim a figure for the pooled class is gone — see
         // desktop/renderer/budget.js). Omitting the field is
         // what tells aegis1 "no cap stated — let effort decide", the same
-        // contract aegiscodex-dev sends.
+        // contract the upstream engine sends.
         //
         // A cap the caller DID state is a different thing, and dropping it was
         // a bug: aegis1 reads a body max_tokens as a ceiling over its ladder,
@@ -960,7 +960,7 @@ function createLocalEngine({
         //
         // Writing is still available, explicitly: the aegis_memory_save tool
         // (mcp/tools.js; the CLI exposes it as /memory). Recall on every turn,
-        // store only what the user asks for — which is what aegiscodex-dev's
+        // store only what the user asks for — which is what the upstream engine's
         // own cross-session memory does, and what this comment claimed to
         // match while sending both halves.
         //
@@ -1324,7 +1324,7 @@ function createLocalEngine({
       let truncationRetried = false;
       let synthesisDone = false;
 
-      // Round cap — the bound aegiscodex-dev has had all along and this engine
+      // Round cap — a bound the upstream engine has had all along and this engine
       // did not. Removing the old fixed cap (12) was right in spirit and wrong
       // in effect: it left the turn with NO horizon, and on 2026-09-15 the
       // question "can you check the plan" ran ~70 rounds, grew the context
@@ -1333,7 +1333,7 @@ function createLocalEngine({
       // re-sends the whole conversation, so an unbounded loop gets more
       // expensive the longer it runs.
       //
-      // The numbers match aegiscodex-dev's (src/autonomous.js) so both clients
+      // The numbers match the upstream engine's (src/autonomous.js) so both clients
       // behave the same: 24 rounds for a chat turn, 40 for an autonomous one.
       // Env-overridable for a deliberately long job.
       // A stated horizon (env) still wins outright — an explicit number is the

package/lib/local/git-scope.js

@@ -4,7 +4,7 @@
  * Minimal git worktree introspection: where the repo root is, and what is
  * dirty right now with a content hash per path.
  *
- * Ported from aegiscodex-dev/src/git-scope.js (ESM → CommonJS). `turn-guard.js`
+ * Ported from the upstream engine reference (ESM → CommonJS). `turn-guard.js`
  * uses `gitRoot` and `gitStatusSnapshot`; the queue now hosts the commit path
  * too, so `foreignChanges` and `scopedCommit` are carried over as well — they
  * were deliberately absent while nothing here queued work, because a copy of

package/lib/local/prompt.js

@@ -2,9 +2,9 @@
 
 /**
  * prompt.js — the desktop client's system prompt (client half of
- * aegiscodex-dev's tool calling).
+ * the upstream engine's tool calling).
  *
- * aegiscodex-dev sends a real persona on every provider turn
+ * The upstream engine sends a real persona on every provider turn
  * (src/backend.js MAIN_CHAT_PROMPT plus a docs/operating-context.md block).
  * The desktop renderer used to send nothing at all, so every model answered a
  * bare user string with no identity, no work rules and no idea which machine
@@ -23,7 +23,7 @@
  * repo roots the host already knows (main.js), so the model stops asking.
  */
 
-/** Identity + work rules. Ported from aegiscodex-dev src/backend.js. */
+/** Identity + work rules. Ported from the upstream engine reference. */
 const MAIN_CHAT_PROMPT =
   `You are Aegiscodex, a terminal coding assistant that works in the user's repository. ` +
   `Help with software engineering tasks: read and reason about code, write and edit files, ` +

package/lib/local/queue.js

@@ -443,8 +443,8 @@ function parsePlanStatus(text) {
       if (line.trim() === '' || /^\s+\S/.test(line)) continue;
       inStatus = false; // anything else (e.g. '---') ends the block
     }
-    // Every PLAN.md in these repos writes `## Phase 7 ✅ — title` (✅ right after
-    // the number). A trailing `## Phase 7 — title ✅` is accepted too, because
+    // Every PLAN.md in these repos writes `## Phase N ✅ — title` (✅ right after
+    // the number). A trailing `## Phase N — title ✅` is accepted too, because
     // reconcile reads plans other sessions and agents wrote, and a heading that
     // says it shipped means it shipped wherever the ✅ sits.
     const hm = line.match(/^##\s*Phase\s+(\d+)\b/);

package/lib/local/shell.js

@@ -2,7 +2,7 @@
 
 /**
  * shell.js — a persistent shell session for the `exec` tool, ported from
- * aegiscodex-dev's src/shell.js (client half of the same design).
+ * the upstream engine reference (client half of the same design).
  *
  * The desktop `exec` tool used to spawn ONE process per call: `cd /foo` in
  * one turn had no effect on the next call, so a model that wanted to work

package/lib/local/tools.js

@@ -2,9 +2,9 @@
 
 /**
  * tools.js — the local tool layer for the desktop agent loop (client half of
- * aegiscodex-dev's tool calling).
+ * the upstream engine's tool calling).
  *
- * Two jobs, mirroring aegiscodex-dev/src/tools.js:
+ * Two jobs, mirroring the upstream engine reference:
  *   1. Tool schemas in the wire format each API family expects — Anthropic's
  *      `{name, description, input_schema}` vs OpenAI-compatible
  *      `{type:'function', function:{name, description, parameters}}`.

package/lib/local/turn-guard.js

@@ -3,7 +3,7 @@
 /**
  * Turn-start foreign-write detection.
  *
- * Ported from aegiscodex-dev/src/turn-guard.js (ESM → CommonJS).
+ * Ported from the upstream engine reference (ESM → CommonJS).
  *
  * Bug this exists for: the commit-time scope check already knew how to tell
  * "my changes" from "somebody else's in-flight work" — but only *after* a

package/lib/local/worktree-lock.js

@@ -3,7 +3,7 @@
 /**
  * Cross-process lock on a git working tree.
  *
- * Ported from aegiscodex-dev/src/worktree-lock.js (ESM → CommonJS).
+ * Ported from the upstream engine reference (ESM → CommonJS).
  *
  * Bug this exists for: nothing keyed on *the working tree*. A session-scoped
  * lock only stops two processes resuming the SAME transcript, so three

package/lib/settings.js

@@ -74,13 +74,13 @@ const CONFIRM_MODE_NAMESPACE = '__confirmMode';
  *  what turns it off. Nothing secret lives here, so no encryption. */
 const MEMORY_PERSIST_NAMESPACE = '__memoryPersist';
 
-/** Reserved namespace for the avatar/companion preferences (Phase 21):
+/** Reserved namespace for the avatar/companion preferences:
  *  `{ enabled, showLevel, motion }` — app-level, not a provider, so it stays out
  *  of the provider CRUD surface for the same reason the AEGIS key does. The
  *  persona itself is deliberately NOT stored here: it is a document, not a
  *  preference, and it lives at `<userData>/avatar/persona.json`, read and
  *  written by main through lib/avatar/store.js so a hand-edited or imported
- *  persona is validated on the way in (see docs/avatar-plan.md §3).
+ *  persona is validated on the way in.
  *  Defaults are the shipped behaviour: the avatar is ON, the level readout is
  *  shown, and motion follows the OS `prefers-reduced-motion` setting. */
 const AVATAR_NAMESPACE = '__avatar';
@@ -374,7 +374,7 @@ function createSettingsStore({ dir, safeStorage } = {}) {
     return memoryPersistState();
   }
 
-  // --- Avatar: reserved namespace, plain preferences (Phase 21) ------------
+  // --- Avatar: reserved namespace, plain preferences ------------
   // The companion's on/off switch, its level readout, and its motion mode.
   // Nothing secret lives here, so no encryption — same reasoning as the quick
   // launcher and memory-persist namespaces above.

package/main.js

@@ -85,7 +85,7 @@ const { createSettingsStore, isReservedNamespace } = require('./lib/settings.js'
 const sessionStore = require('./lib/sync/sessions.js');
 const memoryQueue = require('./lib/sync/memory-queue.js');
 const persistGate = require('./lib/sync/persist-gate.js');
-// Avatar level authority (Phase 20). The ledger, the replay and the award
+// Avatar level authority. The ledger, the replay and the award
 // hooks live here in main — a renderer-held counter is a suggestion, not a
 // fact, the same reasoning persist-gate.js follows. The pure halves
 // (xp.js/level.js/events.js/persona.js) are unchanged and stay IO-free; store.js
@@ -104,7 +104,7 @@ try {
 } catch {
   foreignMemory = require('./vendor/foreign-memory.js');
 }
-// Builtin tool executor for the agent loop (client half of aegiscodex-dev's
+// Builtin tool executor for the agent loop (client half of the upstream engine's
 // tool calling). MAIN-process only: it is reachable from the renderer solely
 // through the whitelisted `tools:` IPC surface registered below — see the
 // sandbox note on registerToolsIpc().
@@ -356,7 +356,7 @@ async function billingResult(run) {
  * would not survive the IPC trip — and the entry is left un-stored so the
  * renderer can keep it in the box and point at the subscribe page.
  *
- * Phase 20 — level authority. This is the memory path's front door, so it is
+ * Level authority. This is the memory path's front door, so it is
  * the first of the award hooks. Two things happen before the write leaves:
  *
  *  1. The entry is *normalised* (store.js `normalizeMemoryEntry`). aegis1
@@ -450,7 +450,7 @@ function quotaFromPayload(data) {
  * 1000 entries x 2 kB over IPC is pure waste, and the bodies are already
  * either in the cloud or in the queue by the time this resolves.
  *
- * Phase 20: each batch that the cloud accepted pays `memory.imported` per
+ * Each batch that the cloud accepted pays `memory.imported` per
  * entry, keyed by the import's own source (foreign-memory.js collapses one
  * source's entries into ONE `import:<source>` session — aegis1 meters distinct
  * session values — so that value is the right per-source key). The replay caps

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "aegis-desktop",
   "productName": "AEGIS Desktop",
-  "version": "0.8.5",
-  "description": "Thin Electron host for AEGIS — a local chat UI over the shared client/aegis.js transport. Ships transport + UI only; engine logic stays server-side.",
+  "version": "0.8.6",
+  "description": "Thin Electron host for AEGIS \u2014 a local chat UI over the shared client/aegis.js transport. Ships transport + UI only; engine logic stays server-side.",
   "author": {
     "name": "AEGIS Code",
     "email": "nborneklint@gmail.com"
@@ -10,11 +10,6 @@
   "license": "MIT",
   "main": "main.js",
   "homepage": "https://aegiscloud.org",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aegisinfo/aegiscode-plugin.git",
-    "directory": "desktop"
-  },
   "bin": {
     "aegis": "bin/aegis.js"
   },
@@ -25,7 +20,8 @@
     "lib",
     "vendor",
     "bin",
-    "build"
+    "build",
+    "docs"
   ],
   "scripts": {
     "start": "electron .",

package/renderer/app.js

@@ -1330,7 +1330,7 @@ function handleQuickLauncherPush(payload) {
 // timestamp, createdAt (epoch ms), source, role, tags[], content, session,
 // importance, summary(bool), topics[], entities[], sentiment, tokenCount,
 // embedding[]. There is no `tier` — L0–L3 is the local CLI engine's concept
-// (aegiscodex-dev/src/memory.js) and does not exist on the cloud rows, so
+// (the upstream engine's memory module) and does not exist on the cloud rows, so
 // source/role are the real provenance axes here.
 //
 // `embedding` is dropped on ingest: it is a raw float vector, sometimes
@@ -1771,7 +1771,7 @@ async function importMemory() {
   els.memoryImportBtn.disabled = true;
   els.memoryHint.textContent = 'scanning for other AI tool memory…';
   try {
-    // Phase 1 — dry run. The scan is read-only against the foreign stores
+    // Dry run. The scan is read-only against the foreign stores
     // (client/foreign-memory.js never writes to them) and the user already
     // asked for the import by clicking, so this runs unattended: no confirm
     // prompt. The preview text left in the hint is the audit trail of what
@@ -1787,7 +1787,7 @@ async function importMemory() {
       .map((s) => `${s.label}: ${s.count}`)
       .join(' · ');
 
-    // Phase 2 — the confirmed write, immediately.
+    // The confirmed write, immediately.
     els.memoryHint.textContent = `importing ${preview.totals.entries} entries — ${detail}`;
     const result = await aegis.memoryImport({ confirm: true, limit: 1000 });
     if (result && result.upgrade) {
@@ -3984,7 +3984,7 @@ async function init() {
   transcript.attachScrollVeto();
   // Read-only diagnostic surface for the headless smoke run
   // (test/electron-smoke.mjs). Everything in this file lives inside the IIFE,
-  // so an injected script cannot otherwise see the scroll veto — the Phase 9
+  // so an injected script cannot otherwise see the scroll veto — the
   // harness read `transcript.isScrolledUp()` directly and silently got `null`,
   // which made its veto assertion unfalsifiable. Exposes state only: no
   // setters, nothing that can drive the UI. Frozen so a stray write in a test

package/renderer/avatar/assemble.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * assemble.js — persona JSON in, layered SVG out (PLAN Phase 22).
+ * assemble.js — persona JSON in, layered SVG out.
  *
  * A pure string builder. It takes a validated persona record plus one
  * expression id and returns the markup, the layer list it walked, and — the

package/renderer/avatar/avatar.css

@@ -1,4 +1,4 @@
-/* avatar.css — the avatar's presentation layer (PLAN Phase 22).
+/* avatar.css — the avatar's presentation layer.
  *
  * Motion is CSS only, and it is the ONE thing in this phase that can be turned
  * off wholesale. Two switches do that, deliberately overlapping:
@@ -35,7 +35,7 @@
   width: 132px;
   height: auto;
   /* The face is decoration: it must never intercept a pointer, a scroll or a
-     drag — the two behaviours Phase 9 protects start as input events. */
+     drag — the two protected behaviours start as input events. */
   pointer-events: none;
   user-select: none;
 }

package/renderer/avatar/avatar.js

@@ -2,7 +2,7 @@
 
 /**
  * avatar.js — the mount: stage, HUD, pane, and the rules that keep the avatar
- * out of everything else's way (PLAN Phase 22).
+ * out of everything else's way.
  *
  * The three modules beside this one are pure or nearly so (`parts.js` is data,
  * `assemble.js` builds a string, `hud.js` builds a view model, `machine.js`
@@ -12,7 +12,7 @@
  *
  *  1. **Never blocks input.** No key listener is registered anywhere in
  *     `renderer/avatar/`, so the avatar cannot consume a keystroke — Escape
- *     still reaches Phase 9's interrupt handler and typing still reaches the
+ *     still reaches the interrupt handler and typing still reaches the
  *     composer, whatever the avatar is doing. Painting is coalesced to at most
  *     one write per animation frame (`schedule()`), so a stream that emits
  *     fifty deltas in a frame still costs one repaint, and every entry point is
@@ -33,8 +33,8 @@
  *     function the storage layer uses, so a persona cannot opt out of the
  *     accessibility preference.
  *
- * Source resolution is deliberately forward-compatible: `window.avatar` (the
- * Phase 21 bridge) is used when it exists, and `preview()` exists so the
+ * Source resolution is deliberately forward-compatible: `window.avatar` is
+ * used when it exists, and `preview()` exists so the
  * harnesses (and the customization pane, which previews edits before anything
  * is written) can drive the avatar without it. Both are one code path — the
  * preview state is an override layer over the real one, and it is labelled as
@@ -77,7 +77,7 @@ function safe(fn, fallback) {
 }
 
 /**
- * The data source. `window.avatar` is the preload bridge Phase 21 will expose
+ * The data source. `window.avatar` is the preload bridge the host will expose
  * (`state()` returning `{ persona, projection, capabilities, warnings }`); when
  * it is missing the avatar renders the honest unknown state rather than
  * inventing numbers.

package/renderer/avatar/cards.js

@@ -2,8 +2,7 @@
 
 /**
  * cards.js — the companion card, rendered in the shape of the tool approval
- * card (PLAN Phase 23, spec §4: "same shape as the approval card the user
- * already trusts").
+ * card.
  *
  * Two things make that more than a styling choice:
  *

package/renderer/avatar/hud.js

@@ -1,8 +1,7 @@
 'use strict';
 
 /**
- * hud.js — the level HUD: XP bar, next unlock, and the honest held state
- * (PLAN Phase 22, spec §1.4).
+ * hud.js — the level HUD: XP bar, next unlock, and the honest held state.
  *
  * The HUD is a *renderer*: it draws a projection main handed it and derives
  * nothing. That is not a stylistic preference — §1.5 of the plan says a level is

package/renderer/avatar/machine.js

@@ -1,9 +1,7 @@
 'use strict';
 
 /**
- * machine.js — the avatar's face, driven by the engine's real signals
- * (PLAN Phase 22: "expression state machine bound to `lib/avatar/events.js`
- * signals").
+ * machine.js — the avatar's face, driven by the engine's real signals.
  *
  * The state machine itself is NOT re-implemented here. `lib/avatar/events.js`
  * is a pure module with no timers and no DOM, and index.html loads that same

package/renderer/avatar/pane.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * pane.js — the customization pane (PLAN Phase 22, spec §3).
+ * pane.js — the customization pane.
  *
  * The whole pane is BUILT FROM THE MANIFEST. Every select is a list of
  * `persona.PARTS` ids, every label comes from `parts.LABELS` (and falls back to
@@ -26,8 +26,8 @@
  *  3. **Nothing here touches input routing.** No key handlers, no focus trap, no
  *     `preventDefault`, no modal. The pane is a plain block of form controls in
  *     the sidebar; opening or closing it cannot consume a keystroke meant for
- *     the composer, and the Escape-interrupt path stays exactly where Phase 9
- *     put it.
+ *     the composer, and the Escape-interrupt path stays exactly where it
+ *     was put.
  */
 
 'use strict';

package/renderer/avatar/parts.js

@@ -1,10 +1,10 @@
 'use strict';
 
 /**
- * parts.js — the layered SVG part manifest (PLAN Phase 22).
+ * parts.js — the layered SVG part manifest.
  *
  * `lib/avatar/persona.js` says it plainly: "Ids only — geometry lives in
- * `renderer/avatar/` (Phase 22), which reads these same ids." This is that
+ * `renderer/avatar/`, which reads these same ids." This is that
  * geometry, and the sentence above is enforced rather than trusted: `IDS` below
  * IS `persona.PARTS`, read from the shared module — this file declares no id
  * list of its own. Adding `hair: 'mohawk-9'` to the persona schema whose
@@ -15,8 +15,8 @@
  * Everything here is DATA. There is no branch on a part id anywhere in the
  * renderer: the assembler walks `LAYERS` in order and emits whatever shapes the
  * manifest holds, so a commissioned art pack or a seasonal outfit is a file,
- * not a fork. That is the whole point of the phase (docs/avatar-plan.md §3:
- * "the avatar is data, not art").
+ * not a fork. That is the whole point of the phase: the avatar is data,
+ * not art.
  *
  * Two deliberate limits, stated here rather than discovered later:
  *

package/renderer/budget.js

@@ -74,7 +74,7 @@ const DEEPSEEK_REASONING_MODEL_RE = /^deepseek-(v4(\.\d+)?-(flash|pro)|flash|pro
 
 /**
  * Effort rung -> tokens. Mirrors EFFORT_TOKEN_BUDGET in
- * desktop/lib/local/engine.js, which mirrors aegiscodex-dev's src/backend.js.
+ * desktop/lib/local/engine.js, which mirrors the upstream engine's src/backend.js.
  *
  * These are the numbers the models whose output length cannot be predicted are
  * sized by, which is why the rung replaced the dropdown: a rung is a
@@ -96,7 +96,7 @@ const EFFORT_TOKEN_BUDGET = { low: 8192, medium: 16384, high: 32768 };
  */
 
 /** An unknown or "auto" rung falls to the top: the same default the engine
- *  and aegiscodex-dev apply, so "auto" cannot silently mean "smallest". */
+ *  and the upstream engine apply, so "auto" cannot silently mean "smallest". */
 function effortRung(effort) {
   return effort === 'low' || effort === 'medium' ? effort : 'high';
 }

package/renderer/index.html

@@ -129,7 +129,7 @@
 
              So the budget is derived from this rung instead. The engine maps
              low/medium/high to 8192/16384/32768 (EFFORT_TOKEN_BUDGET in
-             desktop/lib/local/engine.js, mirroring aegiscodex-dev's
+             desktop/lib/local/engine.js, mirroring the upstream engine's
              src/backend.js), "auto" leaves the choice to the server, and no
              max_tokens is stated by this app at all. The row is always on
              screen: with the dropdown gone there is nothing to swap it for. -->

package/renderer/transcript-view.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * The DOM-touching half of the transcript policy (plan Phase 8), extracted
+ * The DOM-touching half of the transcript policy, extracted
  * from app.js so the two symptoms this work exists to prevent can be asserted
  * *behaviourally* — not just as pure math in stream-policy.js:
  *

package/renderer/usage.js

@@ -68,11 +68,11 @@ function usageTokens(usage) {
 
 /**
  * Rough token count for text the wire never measured — a direct port of the
- * CLI's own estimator (`aegiscodex-dev/src/tokens.js estimateTokens`), and the
+ * CLI's own estimator (the upstream engine's estimateTokens), and the
  * reason its session total is MONOTONIC.
  *
  * This is the whole difference being fixed. The CLI's `appendHistory`
- * (aegiscodex-dev/src/history.js) writes a `tokens` object for EVERY finished
+ * (the upstream engine's history module) writes a `tokens` object for EVERY finished
  * exchange: `{input, output, cacheRead, cacheWrite, real: true}` when the wire
  * reported usage, and `{input: estimateTokens(prompt), output:
  * estimateTokens(reply), real: false}` when it did not. `real` is a FLAG, not a
@@ -477,7 +477,7 @@ function usageBuckets(usage) {
  * Cache hit rate for a usage record: the share of prompt tokens the provider
  * actually served from its cache rather than billing at miss price.
  *
- * Ported from `aegiscodex-dev/src/tokens.js`. It reads through `usageBuckets`
+ * Ported from the upstream engine reference. It reads through `usageBuckets`
  * rather than off the raw object, which is the one deliberate difference: the
  * engine's copy is handed an already-normalised record, while this module is
  * also handed WIRE usage (a provider's raw response body) and ledger rows. A
@@ -588,7 +588,7 @@ function turnAccounting(usage, model, opts = {}) {
   const tokens = usageTokens(usage);
   const u = usage && typeof usage === 'object' ? usage : {};
   // The settled charge can arrive either on the response or folded into the
-  // usage object — aegiscodex-dev/src/main.js does the latter
+  // usage object — the upstream engine does the latter
   // (`{ ...result.usage, costUsd: result.costUsd }`), so both are accepted.
   const settled = typeof opts.costUsd === 'number'
     ? opts.costUsd
@@ -703,7 +703,7 @@ function rollTurn(roll, usage, opts = {}) {
   if (turn.tokens == null) {
     // No reported usage. The CLI does not let such a turn vanish from the
     // total: `appendHistory` estimates it from the text and marks it
-    // `real: false` (aegiscodex-dev/src/history.js), and
+    // `real: false` (the upstream engine's history module), and
     // `aggregateSessionUsage` then adds it like any other row. Folding the same
     // estimate here is what makes the live roll and the rebuilt roll the same
     // number, and what stops the total standing still on exactly the turns the
@@ -772,7 +772,7 @@ function rollMessages(messages) {
  * The ledger row one finished dispatch must carry into the shared session
  * store, so the rolling total can be REBUILT when the thread is reopened —
  * the desktop's counterpart of the CLI's `appendHistory`
- * (aegiscodex-dev/src/history.js:36).
+ * (the upstream engine's history module).
  *
  * One authority for the row, on purpose. The CLI writes a `tokens` object for
  * EVERY exchange and skips none: