ADR-0007 maps today's memory usage onto the contract and mem0: profile card and tasks move to waggle.db, learned facts stay in mem0, extraction runs in the background in batches. Research notes cover what mem0 3.3.1 does and how 68 files use memory today. Two defects found on the way are logged for the main project (UF-025, UF-026).
26 KiB
26 KiB
Upstream fixes for the main Waggle project
This log lists defects in the main Waggle project that we found while preparing the open-source demo edition. Each entry describes what we observed, why it happens, what we did, and what we recommend changing in the main project.
Changes made only to meet the OSS scope (removing billing, tiers, KVARK, team mode and similar) are not defects and are not listed here.
Baseline: commit b20b138 of git.os-dev.tech/oleg.m/waggle-os.
Status values
- Fixed: fixed in the OSS edition. The same fix is recommended for the main project.
- Workaround: worked around without changing the code. The main project needs a proper fix.
- Open: found, not fixed yet.
Entry template
### UF-NNN. Short title
- Status: Fixed | Workaround | Open
- Found: YYYY-MM-DD
- Where: path/to/file.ts:line
- Symptom: what the user or developer sees
- Cause: why it happens
- What we did: change in the OSS edition, or workaround
- Recommendation: what to change in the main project
Summary
| ID | Title | Status | Area |
|---|---|---|---|
| UF-001 | Vendored PptxGenJS runtime is missing from the repository | Fixed | Build, git |
| UF-002 | Setup instructions skip the package build step | Open | Docs, build |
| UF-003 | npm run dev:web cannot authenticate against the sidecar |
Workaround | Web UI, sidecar |
| UF-004 | Packaged macOS and Linux apps likely cannot find the sidecar | Open | Desktop shell |
| UF-005 | Live Stripe webhook secret in git history | Open | Security |
| UF-006 | Conflicting license files in weaver and optimizer | Open | Licensing |
| UF-007 | Onboarding Industry dropdown opens invisibly under the scrim | Fixed | Web UI |
| UF-008 | Local model downloads are cancelled after five minutes | Fixed | Sidecar, local models |
| UF-009 | Model recommendations assume a smaller quantization than the one downloaded | Open | Local models |
| UF-010 | Brand fonts are declared but never loaded | Open | Web UI |
| UF-011 | Token-based shadows compile to nothing | Open | Web UI |
| UF-012 | Border-radius scale is inverted | Open | Web UI |
| UF-013 | Notification fetch failure shows "All caught up" | Open | Web UI |
| UF-014 | Timeline "Edit" button has no action | Open | Web UI |
| UF-015 | Ctrl+Shift+digit app shortcuts never fire | Open | Web UI |
| UF-016 | Tailwind dark: variants never apply |
Open | Web UI |
| UF-017 | Startup text is invisible in the light theme | Open | Web UI |
| UF-018 | Default model shown in the top bar disagrees with Model Pilot | Open | Web UI, models |
| UF-019 | Memory count pluralization: "1 Memories" | Open | Web UI |
| UF-020 | WhatsApp connector bundles GPL-3.0 code into the sidecar | Open | Licensing |
| UF-021 | Settings visual-regression baseline is ignored by git | Fixed | Tests, git |
| UF-022 | Unit tests write into the developer's real ~/.waggle |
Fixed | Tests |
| UF-023 | Four unit-test files fail on macOS | Open | Tests, macOS |
| UF-024 | Workspace packages import packages they do not declare | Fixed | Build, packaging |
| UF-025 | Workspace chat writes entities and error-path messages into personal memory | Open | Memory, privacy |
| UF-026 | Three memory tools of the agent are never wired | Open | Agent, memory |
Entries
UF-001. Vendored PptxGenJS runtime is missing from the repository
- Status: Fixed
- Found: 2026-09-27
- Where:
.gitignore:14(ruledist);vendor/pptxgenjs/package.json(mainpoints todist/pptxgen.cjs.js) - Symptom: on a fresh clone,
npm run dev:servercrashes withERR_MODULE_NOT_FOUNDforpackages/agent/node_modules/pptxgenjs/dist/pptxgen.cjs.js. - Cause: the generic
distignore rule keeps the vendored runtime file out of git. The file exists only on machines where it was created by hand. - What we did: restored the file locally from npm
pptxgenjs@4.0.1. The vendoredtypes/index.d.tsandLICENSEare byte-identical to that release, so the runtime is assumed to be unmodified. SHA-256 of the restored file:873d182a8e2e1c0b5e522ef146117936b96b9b2024667bd4c1de59e2b031d27a. On 2026-10-15 we added the exception!vendor/*/dist/to.gitignore, markedvendor/**as-textin.gitattributesso git keeps the upstream bytes, and committed the file. - Recommendation: add
!vendor/**/dist/to.gitignore(or anchor the rule to/packages/*/dist) and commit the original vendored file. Confirm whether it differs from upstream 4.0.1.
UF-002. Setup instructions skip the package build step
- Status: Open
- Found: 2026-09-27
- Where:
README.md, section "Run from source (development)" - Symptom: following the README (
npm install, thennpm run dev:server) fails withERR_MODULE_NOT_FOUNDfornode_modules/@waggle/core/dist/index.js. - Cause: workspace packages export their compiled
dist/output, which onlynpm run build:packagesproduces. The README does not mention this step. - What we did: ran
npm run build:packagesbefore starting the sidecar. - Recommendation: add
npm run build:packagesto the README, or run it automatically (for example apredev:serverscript), or export package sources for development.
UF-003. npm run dev:web cannot authenticate against the sidecar
- Status: Workaround
- Found: 2026-10-13
- Where:
apps/web/vite.config.ts(proxy optionchangeOrigin: true);packages/server/src/local/index.ts:459(browserBootstrapAuthorityAllowed) - Symptom: the UI on
http://localhost:8080loads, but every API call fails. The console shows "Session bootstrap origin does not match the local service authority" (HTTP 403,SESSION_BOOTSTRAP_ORIGIN_MISMATCH), followed by HTTP 401 on the other endpoints. - Cause: the session-token bootstrap only accepts requests whose page origin equals the request
Host. The Vite proxy runs withchangeOrigin: trueand rewritesHostto127.0.0.1:3333, so the check always fails in the documented dev setup. - What we did: built the UI with
npm run buildand opened it through the sidecar onhttp://localhost:3333, the same way the Playwright suite andinstall.shrun it. No code changes. - Recommendation: set
changeOrigin: falsefor the/apiand/healthproxies soHoststayslocalhost:8080, or allow the dev-server origin explicitly. Confirm the security intent of the bootstrap check first. Update the README accordingly.
UF-004. Packaged macOS and Linux apps likely cannot find the sidecar
- Status: Open (found by reading the code; not yet confirmed by launching a packaged build)
- Found: 2026-09-27
- Where:
app/src-tauri/src/service.rs, functionsresolve_node_pathandresolve_service_script - Symptom: expected error on start of a packaged macOS or Linux build: the shell cannot locate
nodeorresources/service.js. - Cause: both functions look for resources next to the executable (
std::env::current_exe()). That matches the Windows NSIS layout only. On macOS resources live inContents/Resources, on Linux under/usr/lib/<app>. The code never uses Tauri'sresource_dir(). CI builds the macOS app but never launches it. - What we did: nothing yet. Planned in work package P1.3d.
- Recommendation: resolve resources through
app.path().resource_dir()and add a CI smoke test that launches packaged macOS and Linux builds.
UF-005. Live Stripe webhook secret in git history
- Status: Open (action for Egzakta)
- Found: 2026-09-27
- Where: first commit
0c3e2ea, filedocs/launch/drafts/2026-05-12-apps-www-deployment-readiness.md. The value is redacted inb20b138, but it remains in history. - Symptom: anyone with access to the repository history can read the live webhook signing secret. The same document says the live Stripe secret key was left in a chat log and not rotated.
- Cause: a secret was committed in a planning document.
- What we did: the OSS edition will be published from a new repository with a single clean commit; the current history will not be pushed publicly.
- Recommendation: rotate the live webhook signing secret and the live secret key, and treat the existing history as compromised.
UF-006. Conflicting license files in weaver and optimizer
- Status: Open
- Found: 2026-09-27
- Where:
packages/weaver/LICENSE,packages/optimizer/LICENSE;packages/weaver/package.json,packages/optimizer/package.json - Symptom: the LICENSE files say "All rights reserved. This software is proprietary and confidential", while both
package.jsonfiles declare"license": "MIT". - Cause: inconsistent licensing metadata.
- What we did: nothing yet. The OSS edition needs a written decision (question Q6 for Egzakta).
- Recommendation: decide the license for both packages and make the LICENSE files and
package.jsonagree.
UF-007. Onboarding Industry dropdown opens invisibly under the scrim
- Status: Fixed
- Found: 2026-10-13
- Where:
apps/web/src/components/os/overlays/onboarding/WhoAreYouStep.tsx(IndustrySelectContent);apps/web/src/components/os/overlays/OnboardingWizard.tsx:298(.onboarding-scrim,z-[9999]);apps/web/src/components/ui/select.tsx(SelectContent,z-50) - Symptom: on the "Tell us who you are" step, clicking the Industry select shows no options. Clicking just below the select still picks a value.
- Cause:
SelectContentis portaled to<body>with the primitive'sz-50. The onboarding scrim is a fixed full-screen layer withz-[9999], a 92% opaque background andpointer-events: none. The options render under the scrim, so they are invisible, while clicks pass through the scrim to them. - What we did: added
className="z-[10000]"to the IndustrySelectContentand a regression test inWhoAreYouStep.test.tsxthat opens the dropdown and checks that it stacks above the scrim. Checked in the browser: the options are visible and selectable. No other portaled popup renders inside a layer abovez-50(the PersonaSwitcher tooltip is not portaled). - Recommendation: apply the same fix. Longer term, define a shared z-index scale for overlays and popovers instead of independent values, and add a browser-level (Playwright) check for the onboarding flow: the jsdom test can only check classes, not real stacking.
UF-008. Local model downloads are cancelled after five minutes
- Status: Fixed. Verified three ways: (1) unit tests; (2) a real download of
llama3.1:8b(4.7 GB) through the fixed route returned HTTP 200 with a verified digest and a passing generation probe; (3) a scaled-down experiment with Node's realfetchand a 2-second header timeout:stream: falsefailed withUND_ERR_HEADERS_TIMEOUT,stream: truecompleted a 5-second pull. - Found: 2026-10-13
- Where:
packages/server/src/local/routes/local-inference.ts, routePOST /api/local-inference/pull - Symptom: downloading a large local model (observed with
qwen3:30b-a3b, about 18.6 GB) never finishes. The request in the browser stays without a response, and the download stops after exactly five minutes. Ollama's partial files showed 12 of 20 parts last written at 18:05:47, five minutes after the start at 18:00:47; a retry stopped again about five minutes later. The download reached 68% over two attempts. - Cause: the route called Ollama's
/api/pullwithstream: false. In that mode Ollama sends no response headers until the whole model is downloaded. Node's built-infetch(undici) aborts a request after 300 seconds without headers, and Ollama cancels the pull when its client disconnects. Every pull longer than five minutes was therefore cancelled. Ollama keeps the downloaded parts, so each retry resumed, but again for five minutes only. - What we did: the route now requests
stream: trueand reads Ollama's NDJSON progress to the end. Response headers arrive at once, and progress lines keep the connection alive. An{"error": ...}line or a stream that ends withoutsuccessreturns HTTP 502 with Ollama's message. Added two regression tests inpackages/server/tests/local/local-inference-route.test.ts; all 23 route tests pass andtscforpackages/serveris clean. - Recommendation: apply the same fix. Note that the route still has a 45-minute overall timeout and the web UI waits 50 minutes (
apps/web/src/lib/adapter.ts,pullLocalModel). Very large models on slow connections can still hit those limits; a retry resumes, but relaying the streamed progress to the UI would remove the problem and show the user a progress bar. - Follow-up observed on 2026-10-13: after the repeated five-minute interruptions, resuming the same download with the fixed route failed inside Ollama with
remove …/sha256-58574f2e…-partial-0: no such file or directory. Ollama's partial download state had become inconsistent and the previously downloaded data was lost. The fixed route reported this error to the client within two minutes instead of hanging. Consider detecting this error and offering to reset the partial download.
UF-009. Model recommendations assume a smaller quantization than the one downloaded
- Status: Open
- Found: 2026-10-13
- Where:
GET /api/local-inference/models(ranking frompackages/agent/src/cookbook/*);apps/web/src/components/os/model-gate/ModelGate.tsx:393(adapter.pullLocalModel(name)) - Symptom: on a Mac with 16 GB of memory, the model picker ranks
qwen3:30b-a3bfirst with fit "good", estimating 9.2 GB of memory for quantizationQ2_K. Downloading it fetches the default tag, which is about 18.6 GB (Q4_K_M), so the recommended model does not fit the machine once downloaded. - Cause: the fit engine scores each model at its best-fitting quantization (
bestQuant), but the UI pulls the bare catalog name, which resolves to Ollama's default quantization. - What we did: nothing yet.
- Recommendation: either pull the tag that matches the scored quantization (where Ollama publishes one), or score models at the quantization of the default tag. Show the download size and memory requirement for exactly what will be downloaded.
Entries UF-010 to UF-019 come from the UI audit anti-slop/audit-001-2026-10-14.md (found 2026-10-14). "Live" means confirmed in the running app; "code" means found by reading the code and the built CSS.
UF-010. Brand fonts are declared but never loaded
- Status: Open (live)
- Where:
apps/web/tailwind.config.ts,apps/web/src/index.css:213-215 - Symptom: the UI asks for Hanken Grotesk and JetBrains Mono, but the page registers 0
@font-facerules, so most users see the system font. - Recommendation: bundle the fonts (self-hosted
@font-face) or import them, as the design handoff does (docs/design_handoff_waggle_app/design-files/styles/waggle.css:7).
UF-011. Token-based shadows compile to nothing
- Status: Open (code)
- Where: 31 uses of
shadow-[var(--shadow-*)], e.g.OvernightHero.tsx:32,HomeCockpit.tsx:271, 374 - Symptom: Tailwind treats the arbitrary value as a shadow colour, so no
box-shadowis drawn. Intended card elevation and honey focus glows do not render. - Recommendation: define the shadows in
tailwind.config.ts(boxShadow) or useshadow-[...]with a full shadow value.
UF-012. Border-radius scale is inverted
- Status: Open (code)
- Where:
apps/web/tailwind.config.ts(xlmapped to--r-xl= 26px) - Symptom:
rounded-xl(26px) is larger thanrounded-2xl(16px) androunded-3xl(24px); small dropdowns get 26px corners. - Recommendation: restore a monotonic scale and replace the 154 arbitrary radius values with scale steps.
UF-013. Notification fetch failure shows "All caught up"
- Status: Open (code)
- Where:
apps/web/src/hooks/useNotifications.ts:14,NotificationInbox.tsx - Symptom: on a failed request the list is set to empty, and the inbox tells the user everything is read. There is no loading or error state.
- Recommendation: keep loading and error states separate from the empty state, with a retry.
UF-014. Timeline "Edit" button has no action
- Status: Open (code)
- Where:
apps/web/src/components/os/apps/memory/TimelineTab.tsx:237 - Symptom: an icon button labelled Edit has no
onClickand no accessible name; it does nothing. - Recommendation: wire it to editing or remove it.
UF-015. Ctrl+Shift+digit app shortcuts never fire
- Status: Open (code)
- Where:
apps/web/src/hooks/useKeyboardShortcuts.ts:92, help text inKeyboardShortcutsHelp.tsx:12-21 - Symptom: the handler compares
e.keywith digits, but with Shift helde.keyis "!", "@" and so on (US layout), so the documented shortcuts do not work. - Recommendation: match
e.code(Digit0…Digit9).
UF-016. Tailwind dark: variants never apply
- Status: Open (code)
- Where:
apps/web/tailwind.config.ts:4(darkMode: ["class"]), theme switching viadata-theme - Symptom: the
.darkclass is never set, sodark:variants (e.g.ui/alert.tsx:12, chart theme inui/chart.tsx:7) never take effect. - Recommendation: use
darkMode: ["selector", '[data-theme="dark"]']or set.darktogether withdata-theme.
UF-017. Startup text is invisible in the light theme
- Status: Open (code)
- Where:
apps/web/src/main.tsx:12 - Symptom: the "Starting Waggle…" text has a fixed colour
#f6f1e4, while the light theme background is#f7f1e4. - Recommendation: use a theme token for the startup text.
UF-018. Default model shown in the top bar disagrees with Model Pilot
- Status: Open (live)
- Where: top bar model pill; Settings → Models → Model Pilot
- Symptom: the top bar shows "Default model: Llama3.1 (8b)" while Model Pilot shows Primary "Not set" next to "You have a working model".
- Recommendation: show the same source of truth in both places, or explain that Model Pilot is unset and the default comes from elsewhere.
UF-019. Memory count pluralization: "1 Memories"
- Status: Open (live)
- Where: Memory → Trust tab header
- Symptom: with one memory the header reads "1 Memories in this hive".
- Recommendation: pluralize by count.
UF-020. WhatsApp connector bundles GPL-3.0 code into the sidecar
- Status: Open
- Found: 2026-10-15
- Where:
packages/server/package.json:30andpackages/launcher/package.json:42(@whiskeysockets/baileys^7.0.0-rc13);packages/server/src/local/channels/whatsapp-adapter.ts:118,260;scripts/build-sidecar.mjs(EXTERNALlist) - Symptom: Baileys itself is MIT, but it depends on
libsignal6.0.0 (WhiskeySockets/libsignal-node), which is GPL-3.0. Baileys is not in the esbuildEXTERNALlist, so the sidecar build bundles Baileys together withlibsignalintoservice.js, which ships inside the desktop installer. This follows from the build configuration; we have not inspected a built installer. - Cause: the licenses of transitive dependencies are not checked.
- What we did: nothing in the main project code. The OSS edition replaces Baileys with
whatsapp-web.js(Apache-2.0), per Egzakta decision Q5. - Recommendation: include this in the license review (Q6). Shipping GPL-3.0 code inside a binary distributed under other terms is a compliance risk that needs a legal opinion. Options: replace Baileys in the main product as well, or move the WhatsApp connector into a separately installed component. Add a license check for transitive dependencies to CI.
UF-021. Settings visual-regression baseline is ignored by git
- Status: Fixed
- Found: 2026-10-15
- Where:
.gitignore:230(rules*.png);tests/visual/views.spec.ts:19(viewsettings) - Symptom: the visual suite screenshots seven views, but the repository holds baselines for six. The
settings-dark.pngandsettings-light.pngbaselines match thes*.pngignore rule, so they never reach git and the Settings view has no committed baseline. - Cause: a broad ignore rule meant for stray screenshots also matches baseline file names.
- What we did: added the exception
!tests/visual/baselines/**/*.pngto.gitignore. The Settings baselines still need to be generated withnpm run test:visual -- --update-snapshotsand committed. - Recommendation: apply the same exception in the main project and commit the Settings baselines.
UF-022. Unit tests write into the developer's real ~/.waggle
- Status: Fixed
- Found: 2026-10-15
- Where:
packages/marketplace/src/installer.ts:47-50(~/.waggle/plugins/registry.json);packages/marketplace/src/security.ts:183(~/.waggle/security-cache);vitest.setup.ts - Symptom:
npm run testcreates fixture files such asevil-skill-*.jsonandsafe-skill-*.jsonin~/.waggle/security-cacheand creates or overwrites~/.waggle/plugins/registry.jsonwith an empty registry. The developer's own Waggle data directory is modified by the test suite. - Cause: these modules compute their paths from
os.homedir()when they are imported, the tests do not override them, and the Vitest setup does not isolate the home directory. - What we did:
vitest.setup.tsnow pointsHOMEandUSERPROFILEat one temporary directory per test worker before any test module loads, and turns off npm's update notice, which a fresh home would otherwise print into CLI test output. Verified: after the full root suite nothing new appears under the real~/.waggleor~/.claude. - Recommendation: apply the same setup change in the main project, and resolve these paths from the configured data directory at call time instead of at import time.
UF-023. Four unit-test files fail on macOS
- Status: Open
- Found: 2026-10-15
- Where:
packages/server/tests/local/managed-ollama-runtime.test.ts;packages/hive-mind-hooks-openclaw/tests/handler.test.ts:330;packages/server/tests/local/files.test.ts:721;packages/server/tests/local/external-tool-runs.test.ts:1270 - Symptom: on macOS arm64 the root suite has 41 failing tests in these four files. 38 managed Ollama runtime tests fail with "Official runtime archive did not contain ollama.exe". The OpenClaw handler test expects
/var/folders/...and receives/private/var/folders/.... A storage move test is rejected with "escapes workspace root through symlink". An OpenClaw run test times out with "OpenClaw run did not settle". All four files fail the same way when run on their own. - Cause: the runtime fixtures appear to assume the Windows archive layout, and the path checks do not account for
/varbeing a symlink to/private/varon macOS. The OpenClaw timeout is not investigated yet. - What we did: nothing yet. The failures are recorded as known in
docs/oss/baseline.md. - Recommendation: make the runtime fixtures platform-aware, compare resolved paths (
fs.realpathSync) in path assertions, and run the unit suite on macOS and Linux in CI.
UF-024. Workspace packages import packages they do not declare
- Status: Fixed
- Found: 2026-10-15
- Where:
package.jsonofpackages/server,packages/agent,packages/launcher,packages/worker,packages/cliandapps/web - Symptom: inside the monorepo everything works because npm hoists all dependencies to the root
node_modules, but a package installed on its own fails to resolve imports.serverimports@waggle/marketplace,@waggle/sdk,@waggle/weaver,zod,@anthropic-ai/sdkand@ax-llm/axwithout declaring them;agentimportspdf-parseandplaywright-core;workerimports@waggle/waggle-dance;launcherimports@waggle/server;apps/webimports@waggle/shared.serverdeclares@waggle/hive-mind-shim-coreandclideclares@waggle/weaverwithout using them. - Cause: no check compares imports with declared dependencies.
- What we did: declared the missing dependencies (
playwright-coreas an optional peer, becauseagentloads it only when available;@waggle/serveras a dev dependency oflauncher, because its build bundles@waggle/*), removed the unused ones, and addedscripts/check-workspace-deps.mjs(npm run check:deps) to CI. - Recommendation: apply the same declarations in the main project and run the check in CI.
UF-025. Workspace chat writes entities and error-path messages into personal memory
- Status: Open
- Found: 2026-10-16
- Where:
packages/server/src/local/index.ts:1298(createSessionOrchestratorbuilds every session orchestrator onmultiMind.personal);packages/server/src/local/routes/chat.ts:3435and:3786 - Symptom: in a workspace chat, entities extracted from the agent's answer and, on the error path, the user's message are written to the personal mind, not to the workspace mind. The comment at
chat.ts:3428says they go to "the knowledge graph of the active workspace mind". Workspace content leaks into personal memory, which follows the user into every other workspace. - Cause:
getKnowledge(),getFrames()andgetSessions()on the orchestrator return the layers of the database it was built on, which is always the personal one; the workspace mind is only attached withsetWorkspaceMind. - What we did: nothing in the old code. Found by reading the code, not reproduced at runtime. In the community edition these writes move to the memory contract in P1.5, where the scope is explicit on every call.
- Recommendation: write through the workspace layers when a workspace mind is attached, and add a test that a workspace chat leaves the personal mind unchanged.
UF-026. Three memory tools of the agent are never wired
- Status: Open
- Found: 2026-10-16
- Where:
packages/agent/src/orchestrator.ts:187(the onlycreateMindToolscall);packages/agent/src/tools.ts:96-109,:314,:474,:657 - Symptom:
search_all_workspacessearches only personal memory although its description promises all workspaces;correct_knowledgealways answers "Feedback handler not available. Cannot correct knowledge."; the embedding-based duplicate check insave_memorynever runs. - Cause:
createMindToolsis called withoutgetAllWorkspaceSearches,feedbackandembedder, and each tool silently falls back when its dependency is missing. - What we did: nothing in the old code. In the community edition these tools are rebuilt on the memory contract in P1.5.
- Recommendation: pass the three dependencies, or remove the tools whose dependency cannot be provided so the agent is not offered a tool that cannot work.