feat(operations): core primitive, resources, transfer events and ctx.operations (#895, 1/6)

[markhayden]

Part of #895 (PR 1 of 6). Spec: .claude/specs/operations-progress/SPEC.md (rev 3.1, approved). Plan: .claude/specs/operations-progress/PLAN.md (rev 6, approved after five Codex review rounds).

This PR builds the core of operations: one progress system for every long-running flow. There is no UI yet, and no existing flow switches over yet. PRs 2–6 add the UI and switch the flows over one at a time.

What's in it

• T0 — antfly spike (tasks/evidence-antfly-pull.md):
  • inference pull downloads into a separate staging folder, publishes the model atomically at the end, and resumes where it left off after SIGTERM/SIGKILL.
  • Its stderr reports structured progress, so model pulls can be cancelled at any point.
  • It ignores ANTFLY_HOME, so it needs --models-dir.
  • SPEC D12 and PLAN 5.2 are updated with these findings.
• SDK types (packages/sdk/src/types/operations.ts):
  • plan and stages, the full operation view, the context installers report through, and outcomes;
  • the shared quiet/stuck rule (pure, used by server, CLI and UI);
  • the wire shapes and the plugin API types.
• Registry (packages/core/src/operations/registry.ts):
  • identical requests attach to the running operation;
  • cancel is allowed only before the point of no return, and "cancelled" is reported only after the work has stopped;
  • two clocks (output proves the work is alive, but only real progress counts as progress);
  • every event carries the complete view and a revision number;
  • one audit record per operation, eviction of old entries, and a log line when the server stops.
• Resources (resources.ts):
  • three lock files acquired in a fixed order: install-state (the existing ~/.bakin/install.lock), then media-store, then search-engine;
  • waiting can be aborted, and locks left by dead processes are reclaimed;
  • one ownership context, so the legacy withInstallLock (now built on top of this) keeps working inside an operation.
• runLocal runs an operation in-process. src/core/operations.ts is the per-process registry, wired to SSE and the audit log.
• One download function (packages/core/src/net/download.ts):
  • every download reports progress, stall and retry events and can be cancelled;
  • downloadText and opTransfer live alongside it;
  • pack bins, model files, Whiskit, plugin sources, artifact upgrades and the antfly engine now go through it (the engine streams instead of loading the whole file into memory);
  • src/core/whiskit/download.ts is deleted.
• HTTP:
  • GET /api/operations[/:id] and POST /api/operations/:id/cancel, each answering with the server's bootId;
  • a shared startOperationResponse helper for converted routes (202 within 500ms);
  • the routes are declared in core-routes and the OpenAPI docs.
• ctx.operations for plugins:
  • kinds and fingerprints are prefixed with the plugin id;
  • the core resources are reserved for core plugins;
  • the SDK testing harness runs a real registry that keeps its locks in memory.
• Docs: .claude/knowledge/operations.md, a CLAUDE.md Key Patterns entry plus the ~/.bakin folder map, the plugin guide's "Long-Running Work" section, and corrections to the install-lock descriptions in three knowledge docs.

Fixed along the way

• Download race: an attempt that failed very quickly could leave a file-open error behind as an unhandled rejection after the caller had deleted its temp folder. A regression test fails without the fix.
• Test isolation: resource names were checked by computing their lock path, which looked up the Bakin home folder. The test-isolation guard caught this; name checking is now pure.

Commit strategy

Each commit is green on its own. Reverts go in reverse order:

• the 1.5 commit 844dd5faf (the caller switch) reverts as one unit;
• the prepare commits revert after the commits that use them.

The lock file only gained extra holder fields, and older readers ignore them.

Verification

• bun run test: 10,622 of 10,628 pass (18 skipped). The 6 failures are the compiled-binary suites, which fail on the author's Mac because macOS kills every Bun 1.3.13 compiled binary, even a trivial one. CI on Linux runs them.
• typecheck, lint (0 errors) and check:cycles pass.
• ui:conformance --quick passes with the Bits checkout at its pinned commit.
• docs:validate and docs:validate:routes pass.
• Isolated boot with safe antfly settings: GET /api/operations returns { bootId, operations: [] }, and the 404s carry the bootId.

UI conformance: no UI changes in this PR (the browser pattern comes in PR2).

🤖 Generated with Claude Code