- Drop the "pass-through remains for back-compat" note on
AppDatabaseBase's domain modules; the pass-through layer is gone, so
the comment was out of date. Replace with a pointer to the ESLint
guard that blocks regression.
- Flag the two remaining >500-line files (`agent-runtime/runtime-bridge.ts`
648 LOC, `agent-runtime/artifact-projector.ts` 637 LOC) with an
inline `TODO: decompose — M-followup` note. No structural change;
the decomposition is tracked for a later milestone to keep this pass
scope-safe.
Classify scheduler, orchestration, IPC read, and automation catch
blocks via logAppError + classifyUnknownError so each failure surfaces
a stable `module.subdomain.condition` code plus a kind. No behaviour
change — returns, throws, and fall-through are preserved; only log
prefixes and the taxonomy metadata are new.
Wave 1 coverage (26 sites, all non-database):
- orchestration/scheduler-lock-recovery (3)
- orchestration/scheduler-housekeeping (5)
- orchestration/scheduler-idle-automation (2)
- orchestration/scheduler-heartbeat (4)
- orchestration/turn-context (2)
- ipc-core-read-handlers (6)
- automation/automation-handlers (4)
Relax the Logger interface so `error` is optional, letting callers
whose deps expose only `{info, warn}` (scheduler contexts) pass in
directly without wrapping. The helper falls back to warn when error
is absent.
Migrate all remaining pass-through call sites (social, skills, budget,
entityCrud, documents, knowledge, automation, wakeup, backup, threads,
settings, snapshot, connectors, workspaces, activity) to their owning
domain modules. `AppDatabase` now carries only three methods:
- createHireRequest (multi-module composite: agents + approvalsMod)
- rollbackConfigRevision (multi-module composite: documents + entityCrud)
- queryAll (raw-SQL escape hatch, @internal)
The vault/env-binding infrastructure previously passed argument-by-
argument into `entityCrud.saveSecret`/`resolveSecretEnv` now binds at
module construction, letting callers invoke `db.entityCrud.saveSecret({...})`
without carrying vault plumbing.
Structural types that narrowed AppDatabase to a bag of flat methods
(`ConnectorModelPolicyDeps` callers, `CapabilityMatchDb`, test mocks in
budget-enforcement / budget-incidents / task-quality-gates /
failure-escalation / task-quality-gates-sweep) are reshaped to the new
namespace. `connectorPolicyDepsFromDb` replaces the old pattern of
handing the whole AppDatabase to `validateConnectorModelSelection`.
A new ESLint rule in eslint.config.mjs blocks new top-level methods on
AppDatabase so the pass-through layer cannot silently grow back.
`AppDatabase.ts` dropped from 193 lines to 58; `AppDatabaseBase` lost
the 270-line trailing pass-through block.
Rewrite ~376 call sites for messages, runs, approvalsMod, and company
domains and delete the corresponding pass-through methods on
AppDatabase / AppDatabaseBase. Structural type references
(ReturnType<HandlerDeps["db"]["getRun"]>) and SweepStaleReviewsDeps-style
mocks are updated to route through the owning sub-module.
Rewrite ~525 call sites from `db.<method>()` to `db.<module>.<method>()`
for tasks and agents domains (including `getAgent`/`findAgent`/`getTask`
which live on the `entityCrud` field). Delete the corresponding
pass-through methods on AppDatabaseBase. Structural types that narrowed
`db` to a bag of flat methods (CapabilityMatchDb, EscalationDeps,
SweepStaleReviewsDeps) are reshaped to match the new namespace. Internal
callback references inside database.ts/database-base.ts now invoke the
owning module directly (e.g. `this.agents.saveAgent`) rather than the
deleted pass-through.
The codemod lives at scripts/codemod/remove-appdatabase-passthrough.mjs
and filters by owning module + optional explicit method list. It is
idempotent and does not re-rewrite already-namespaced calls.
- backup.ts: log.warn when `git rev-parse HEAD` fails so sandbox/CI runs
with no git show diagnosably instead of silently emitting gitSha:null
(Karpathy review ask).
- backup.ts: expand comment on VACUUM INTO to pin the WAL-mode invariant
— future readers must not "helpfully" add a wal_checkpoint call
(Karpathy review ask).
- C6.2 proposal: add hard coordination gate before wave 3 because
commit 0db6e42 already demonstrated the race hazard when two agents
touch scripts/ / connector-definitions/ in the same window
(Linus review ask).
Consolidate the two runtime messaging modules under src/main/messaging/. Storage stays in database/messages.ts — that is the SQL layer and belongs with the other DB modules; messaging/ covers the dispatch/normalize runtime around it.
- message-dispatch.ts -> messaging/dispatch.ts
- message-normalize.ts -> messaging/normalize.ts
- add messaging/index.ts barrel for future consumers (existing call sites import the concrete module path directly)
- 10 call sites updated across src/main and tests
Replaces the stub recorder with a real-provider CLI. The command now:
1. Reads system prompt + user message from files on disk (empty files
are rejected — a fixture with no prompt captures no behaviour).
2. Resolves the provider spec from `--provider anthropic|openai|google`
and pulls the API key from the matching environment variable.
Missing env → hard error with a copy-pasteable export hint; no
fallback, no mock.
3. Calls `streamSimple` from @mariozechner/pi-ai with the user-picked
model. On provider error (stopReason=error|aborted) the CLI exits
non-zero and writes no JSONL. Users re-run if they think the
failure was transient.
4. Serialises one user turn + one assistant turn + an empty
assertions block into the JSONL shape documented in
tests/eval/README.md. Token ledger comes straight from the
assistant message's usage field (renamed to snake_case for
provider-neutral on-disk format).
Scope is deliberately single-turn: tool use / multi-turn agent loops
are B5.1's job. Importing the AgentCompany worker's system prompt
builder would require the Electron runtime; the CLI stays node-only
so it can run standalone.
`--help` works and prints the argument matrix. All failure modes exit
non-zero with a specific, actionable message.
Also document the new recording workflow in tests/eval/README.md —
four-step procedure, example scenario files, assertion templates, and
explicit list of what the recorder still does not do.
32dfa89 renamed the three catalog data files into src/main/connector-definitions/ but left src/main/connector-definitions.ts pointing at the old connector-definitions-data-* paths, which no longer resolve. Fix the barrel to import from ./connector-definitions/index and correct each moved file's ConnectorDefinition import to walk up one level (../connector-definitions).
Partitions the remaining catch sites into three waves (worker +
orchestration, IPC surfaces, database + credentials) so each wave is
one coherent review and can land in parallel with the B2 migration
precondition work that depends on classified DB catches.
Non-goals are explicit: no observable behaviour change, no renderer-
side coverage, no Result<T, AppError> envelope. The proposal exists
so the error taxonomy reaches the 95%+ coverage a lint rule needs.
lessons.md does not exist in this repo and is user-private in other workspaces. CLAUDE.md's self-evolution bullet now points at the project-level AGENTS.md, which is actually checked in and maintained. Build-artifact gitignore coverage (out/, build/, dist/, boss-build/, local-release/) was already in place — no change needed for N5.
Each of these catches already logged via an accessible `logger` or `log`.
The migration wraps the thrown value through `classifyUnknownError(raw,
fallback)` and emits the log line with the structured `[code]` prefix.
Observable behaviour — return values, fail strings, DB writes — is
unchanged; the only addition is a machine-readable `code` on every log
line so future telemetry can bucket by category.
Sites migrated (11 files, 20 catch sites):
src/main/browser-action-service.ts (2) approval lookup, payload JSON
src/main/ipc-credentials-handlers.ts (4) save, remove, test lookup, test resolve
src/main/hire-hook.ts (3) getAgent, connector def, outer exception
src/main/checkpoint-engine.ts (2) onTaskStarted, onDocumentDrafted
src/main/document-lifecycle.ts (1) getRun while deriving taskId
src/main/skills/runtime.ts (2) builtin statSync, builtin readdir
src/main/worker/handlers/run-status-handler.ts (1) run not found during status
src/main/worker/handlers/run-log-handler.ts (1) lease renewal lookup
src/main/notification-service.ts (1) notification.close during destroy
src/main/updater-service.ts (1) autoUpdater.checkForUpdates
src/main/ipc-support.ts (2) ipc handler throw, emitEvent send
Why only 20 tonight: 248 catches exist in src/main/. Rewriting them all
in one commit is high-diff-risk (collides with Linus's in-flight
database/backup/migration work on database/*, connector-definitions-*,
message-* and scripts/*) and low-value (pure-library catches with no
accessible logger produce dead `void classified` constructs). The
taxonomy module is committed separately so the remaining 228 sites can
land incrementally via the C6.2 proposal.
All 11 files selected sit outside Linus's working set. Verified:
- pnpm typecheck clean
- pnpm test:unit 498 passed
The `agent_messages.read_at` column has had no production writer since
v12 moved read tracking into the per-viewer `agent_message_reads`
receipts table. It survived anyway, carrying a NULL through every SELECT
list and begging the next maintainer to accidentally read stale data
from it.
- v49 migration: `ALTER TABLE agent_messages DROP COLUMN read_at`
(idempotent: skips if absent).
- messages.ts: SELECTs no longer fetch the column; per-viewer `readAt`
is computed from `agent_message_reads` as before, with `null` for
call-sites that have no viewer context (getAgentMessage /
searchMessages / listAgentInboxUnread).
- runtime-bridge.ts / runtime-message-injector.ts: comments referencing
the dropped column updated to name the read-receipts table instead.
Before running any pending migration, take a synchronous snapshot of the
profile to backups/pre-migration-v<target>-<ts>/ and write a
backup-manifest.json recording reason, schema version, app version, and
git SHA. A failed migration now has a well-labelled recovery point
instead of a half-upgraded profile.
- createAutomaticBackup(reason): synchronous snapshot via VACUUM INTO +
recursive cpSync of logs/artifacts, plus JSON manifest. No fallback —
failure throws so the caller refuses to touch the schema.
- runMigrations accepts createAutomaticBackup and invokes it when any
migration is pending. No optional chaining; callers must supply it.
- AppDatabase constructor takes appVersion so main-runtime stamps the
manifest with app.getVersion().
Establishes `src/main/errors/` with:
- `AppError` base + `Recoverable|UserInput|Upstream|Fatal` subclasses
keyed on a narrow `ErrorKind = "recoverable" | "user_input" |
"upstream" | "fatal"` union. Four kinds is deliberate: adding a fifth
is a conscious proposal, not an inline decision at a catch site.
- `classifyUnknownError(e, fallback)` — required-fallback-meta wrapper
that refuses to invent classification. If `e` is already an
AppError it is returned untouched; otherwise the call site's
intent wins and the raw value is preserved via `cause` (for Error
instances) or `context.raw` (for anything else).
- `logAppError(logger, raw, fallback, level?)` helper emits one
structured log line and returns the classified AppError so the
caller can still branch on `err.kind`.
Why this module exists: 248 catch blocks in src/main/ today are
overwhelmingly `} catch {}` or `log.warn(); return default`. Behaviour
is correct case-by-case but the codebase has no machine-readable signal
for "is this recoverable vs fatal", making it impossible to write
graceful-shutdown logic, telemetry buckets, or catch-site audits.
Part 2 migrates the top-20 high-frequency catch sites. Part 3 (tracked
as C6.2 proposal) covers the remaining 228.
No behavioural change in this commit — it only adds the classifier and
exports.
- harness.test.ts: add in-memory self-test layer (pass + fail + purity), guard
fixtures dir with existsSync so absent dir yields empty list without
crashing the runner. Empty-fixture pnpm test:eval now carries real signal.
- replay-client.ts: remove dead if (!turn) branch; cursor bounds-check above
already guarantees the element. Use non-null assertion with a comment.
- assertion-judge.ts: drop unnecessary (turn as AssistantTurn | { content:
unknown[] }) cast. turn.role === assertion.role already narrows to
UserTurn | AssistantTurn and both expose .content.
- _BLOCKED-BY-CONSTRAINT.md: correct electron-builder note. files: is a
whitelist, so tests/eval is automatically excluded and no new rule is
required.
Document the follow-up tier on top of the B5 assertion harness: thin
single-call rubric judge, additive RubricDimension/RubricVerdict types,
cost cap ($2/run) with loud-skip behavior, per-fixture rubric cap (8
dimensions), baseline acceptance workflow, and explicit trigger
conditions (10+ fixtures / 2 incidents / structural-miss / 50-run zero
catch) — do not build speculatively.
Roundtable outcome: 2-1 to defer tonight. Linus — don't bolt a second
LLM to an empty harness. Jobs — single signal first. Karpathy — fixture
accumulation is what will tell us which rubric dimensions matter; the
schema stays extensible so we can add rubric-per-fixture without
breaking B5.
Collects the five post-run diagnostic + escalation modules into src/main/worker/observability/: run_events persistence, stdout/stderr noise filter, credential-shape log redactor, self-wake circuit breaker, and retry-aware failure escalation pipeline. circuit-breaker.ts and failure-escalation.ts remain as standalone files inside the directory — each owns a distinct state machine that deserves its own boundary — rather than collapsing into a single index.ts. handlers/*.ts and tests/unit/*.test.ts updated to point at the new paths.
Groups the pi Agent lifecycle, factory, signature contract, and env/redaction helpers into src/main/worker/runtime/. WorkerRunner is the module's public entry and lives in runtime/index.ts; pi-agent-factory and pi-hook-contract stay named for their role as visible runtime boundaries; helpers.ts carries ParentMessage/ChildMessage/RunJob types plus redactor + env override utilities. entry/index.ts and agent-runtime/runtime-message-injector.ts updated to import from the new paths.
Land the B5 harness skeleton: fixture loader (strict JSONL contract with
meta header + ordered turn records + assertions tail), replay-client that
swaps in for pi-ai's streamSimple by replaying recorded assistant turns,
structural assertion judge (tool_called / no_tool_called /
message_contains_substring / tool_call_arg_matches / trace_max_turns), an
eval-runner that sums the token ledger and produces an EvalResult, a
vitest driver (tests/eval/harness.test.ts) that discovers *.jsonl
fixtures, and a record-fixture CLI that writes fixture meta headers.
Hard contracts:
- No fallback: replay-client and fixture-loader throw on exhaustion /
malformed input rather than synthesizing defaults.
- No mock: types reuse @mariozechner/pi-ai AgentMessage / ToolCall
verbatim; shadow types are forbidden.
- No fake fixture data: tests/eval/fixtures/ ships only README +
.gitkeep. Real traces are recorded by the user against live providers.
package.json adds test:eval (vitest --passWithNoTests so an empty
fixture dir is green) and eval:record (CLI entrypoint). electron-builder
already excludes tests/ via its files: glob — fixtures never enter the
shipped .asar.
Pulls the worker process entry point, parent<->worker IPC plumbing, message validation schema, and crash-recovery handler into a single src/main/worker/entry/ module. No runtime behavior changes — only directory + file-name renames plus import-path updates: worker-entry.ts -> entry/index.ts, worker-message-handler.ts -> entry/message-handler.ts, worker-rpc.ts -> entry/rpc.ts, worker-crash-recovery.ts -> entry/crash-recovery.ts, worker-types.ts -> entry/types.ts. electron.vite.config.ts, worker-service.ts, handlers/*.ts, pi-agent-factory.ts, and worker-runner.ts updated to point at the new locations.
Adds src/main/worker/pi-hook-contract.ts, a compile-only contract that re-states every pi-agent-core hook callback shape (beforeToolCall / afterToolCall / transformContext) as a named alias and pins the local worker implementations against them via type-level ExpectHookType assertions. pi-agent-factory.ts imports the contract for side effects so tsc drags it into the build graph. A future pi upgrade that renames a field or changes an argument now fails typecheck here instead of at first destructive tool invocation.
The operator's mental model: a chat is a room, @X means "X takes the
turn", unmentioned participants keep working. Two separate gaps were
letting 张工程师 answer when the user wrote "@CEO 更新一下进度" inside
their Board↔张工程师 chat:
* `resolveMessageWakeTargets` always woke the DM recipient, regardless
of who the body @-mentioned. CEO woke too, but 张工程师 — the
addressed party — replied first and CEO's busy-queued wake arrived
after the operator had already taken the earlier reply as "the
answer". Explicit mentions now shadow the implicit DM recipient:
with mentions, only the named agents wake; the recipient still sees
the message in their inbox, they just aren't obliged to answer.
No mentions → fall back to the historical "DM wakes the recipient"
contract so every existing flow is untouched.
* `channel-utils` keyed each chat by `sort(fromAgent, toAgent)`. CEO's
reply with `toAgentId=__board__, parentMessageId=<original>` landed
in a fresh Board↔CEO pane — the exact "new session" the operator
complained about. Walk `parentMessageId` back to the root of the
reply chain and use the root's participant pair: every reply in a
thread now collapses into the chat the sender originally opened,
cycle-guarded against malformed parent pointers.
Pinned by a new unit test: DM to CTO with "@CEO 更新一下进度。" wakes
only CEO while keeping the message visible to both CTO's and CEO's
inbox.
A DM addressed to one agent that @-mentions another was silently
dropping the second agent out of the conversation:
* `dispatchAgentMessage` added the mentioned agent to the wake set,
so CEO's heartbeat fired — but
* `listAgentInboxUnread` only surfaced messages where the current
agent was `to_agent_id` or sat in a matching channel/project/
department. Mentions were invisible, so CEO's next turn saw nothing
new and returned silently. From the operator's chair this looked
exactly like "CEO ignored me; 张工程师 answered instead".
* `findMentionedAgentIds` had a latent bug on top: its unique-alias
filter used `ids.length === 1`, but a single agent whose name
matched its role registered itself twice, tripped the filter, and
every `@CEO` in a scaffold with role === name was a no-op. Once
inbox visibility was fixed the bug became load-bearing.
Root-cause fixes:
* New migration v48 adds `agent_message_mentions(message_id, agent_id,
company_id, created_at)` so mention fan-out is a first-class join.
* `sendAgentMessage` now takes the resolved mention set and writes
the row + mentions in a single transaction — a crash between the
two writes can no longer leave a message visible to the recipient
but invisible to the mentioned agent.
* `dispatchAgentMessage` computes the mention set exactly once via
`resolveMentionedAgentIds` and hands the same list to both the DB
write and `resolveMessageWakeTargets`, so persistence and wake
stay in lockstep.
* `listAgentInboxUnread` and `listAgentMessages` gain an `id IN
(select message_id from agent_message_mentions …)` clause so the
mentioned agent's inbox actually contains the message that woke it.
* `findMentionedAgentIds` now stores per-alias agent IDs in a `Set`
and filters on `ids.size === 1`, dropping the self-duplication
bug while preserving the "refuse ambiguous aliases" semantics.
* Company teardown drops `agent_message_mentions` alongside the
existing `agent_message_reads` cleanup so deletes stay clean.
Tests pin the new behaviour: a DM with a `@CEO` mention reaches
CEO's inbox and both agents get woken, while a DM whose recipient
is `__board__` never attempts to wake the human sentinel.
Three independently ugly bugs that all fed the same log flood:
* Electron's `WebFrameMain.send` writes every "Render frame was disposed"
to stderr via `console.error`. When the worker fans a second
agent-event past a reloading renderer, we produced thousands of
identical lines and stalled the main loop on stderr I/O. Added a
`mainFrame.detached` guard so the send is short-circuited before
Electron's own catch block fires, and installed a targeted filter in
`suppress-warnings.ts` (now actually imported from the entry point)
so the specific `console.error("Error sending from webFrameMain:"…)`
noise never reaches the terminal. Any other payload still surfaces.
* `dispatchAgentMessage` accepted the human-reader sentinel as a wake
target when an agent replied to `__board__` — `wakeAgentIfPossible`
then called `db.getAgent("__board__")`, threw, and the dispatcher
kept repeating on every send. Strip `HUMAN_SENDER_ID` at
`resolveMessageWakeTargets`, and keep a defense-in-depth guard in the
heartbeat so a stray caller (future automation fan-out) cannot
reintroduce the crash.
* Pi's skills loader rejects any SKILL.md whose frontmatter `name`
diverges from its parent directory. The four bundled `my-writing-style`
copies declared `name: writing-style-skill`, so every install emitted
a warning and dropped the skill. They also lived as orphan gitlinks
(mode 160000 without .gitmodules), and the global `*.md` gitignore
hid every other SKILL.md from version control. Fixed the frontmatter
to match the dir, converted the dangling submodules to plain trees,
and allowlisted `builtin-skills/**/*.md` so a fresh clone carries the
catalogue instead of silently losing it.
The previous pass "aligned" model-resolver.ts to
accounts/fireworks/models/kimi-k2.5-turbo — the per-token model path —
to match the connector catalog's default. That was the wrong direction:
Fire Pass subscription traffic routes exclusively through
accounts/fireworks/routers/kimi-k2p5-turbo (see docs.fireworks.ai/firepass),
and the entitlement does not attach to the per-token id. Existing agent
rows already pointed at the router id, so validateConnectorModelSelection
rejected every dispatch with "does not allow model
'accounts/fireworks/routers/kimi-k2p5-turbo'" and the CEO stopped running
entirely.
Put the router id back in model-resolver.ts (the enabled-pool source of
truth), and bring the two catalog defaults in line so a freshly-seeded
Fire Pass connector also ends up on the router id. The per-token
`fireworks` connector keeps the `models/...` default since that path
bills per token and genuinely targets the per-model endpoint.
triggerSelfWake fired only when the completing agent had at least one
actionable task (todo / in_progress). A CEO in team_building mode has
zero tasks by definition — each heartbeat hired one or two agents,
returned, and then waited for the next 2-minute timer tick. Operators
watched bootstrap crawl: in the captured field log, six heartbeats
burned 12 minutes before the first hire landed.
Teach triggerSelfWake to also chain when the agent is a top-level CEO
with active goals, zero active direct reports, and no already-pending
hire_agent approvals — the exact state team_building.en.md is telling
the model to resolve. The existing circuit breaker (MAX_CONSECUTIVE_WAKES
without progress) still applies, so a CEO that keeps returning without
filing hires gets paused and its manager wake — the board / human —
is raised instead.
Once reports activate or all intended hires are filed, the predicate
flips to false and runs resume the normal heartbeat cadence.
ZacharyZhang-NY