refactor(session): Session Actor Refactor — pure reducer, effect executor, SessionBridge deletion

.gitignore

@@ -1,3 +1,4 @@
+node_modules
 node_modules/
 dist/
 *.tsbuildinfo

engineering_best_practices.md

@@ -0,0 +1,78 @@
+# Comprehensive Guide to Software Engineering Best Practices
+
+## Introduction
+
+Software engineering is not merely about writing code that works; it is about creating systems that are maintainable, scalable, secure, and resilient. As software increases in complexity, adhering to established best practices becomes the dividing line between a project that thrives and one that collapses under its own weight (technical debt). This essay explores the foundational pillars of modern software engineering: Code Quality, Architecture, Testing, Processes, and Security.
+
+## 1. Code Quality and Maintainability
+
+### 1.1 Readability as the Primary Metric
+Code is read far more often than it is written. "Clever" code that obscures intent is a liability.
+- **Naming Conventions:** Variables and functions should be self-documenting (e.g., `calculateTotalRevenue()` vs `calc()`).
+- **Small Functions:** Functions should do one thing and do it well (Single Responsibility Principle).
+- **Comments:** Comments should explain *why* something is done, not *what* is done. The code itself should explain the *what*.
+
+### 1.2 The DRY Principle (Don't Repeat Yourself)
+Duplication leads to inconsistency. If logic is copied in three places, a bug fix must be applied three times. Abstraction and modularity allow for single sources of truth.
+
+### 1.3 SOLID Principles
+- **S**ingle Responsibility: A class should have one reason to change.
+- **O**pen/Closed: Open for extension, closed for modification.
+- **L**iskov Substitution: Subtypes must be substitutable for their base types.
+- **I**nterface Segregation: Many client-specific interfaces are better than one general-purpose interface.
+- **D**ependency Inversion: Depend on abstractions, not concretions.
+
+## 2. Architectural Integrity
+
+### 2.1 Modularity and Decoupling
+Systems should be composed of loosely coupled components. Changes in a UI module should not break the database layer. This is achieved through clear boundaries, interfaces, and dependency injection.
+
+### 2.2 Scalability
+- **Horizontal vs. Vertical:** Design systems that can scale out (adding more machines) rather than just up (adding more power).
+- **Statelessness:** Stateless services are easier to scale and recover from failures.
+
+### 2.3 Simplicity (KISS)
+Complexity is the enemy of security and reliability. Avoid over-engineering. "You Aren't Gonna Need It" (YAGNI) reminds us to implement only what is necessary for current requirements, not future hypotheticals.
+
+## 3. Testing Strategies
+
+### 3.1 The Testing Pyramid
+- **Unit Tests:** The base. Fast, isolated, and numerous. They test individual functions or classes.
+- **Integration Tests:** Verify that different modules work together correctly.
+- **End-to-End (E2E) Tests:** The tip. Slower and more brittle, simulating real user scenarios.
+
+### 3.2 Test-Driven Development (TDD)
+Writing tests *before* implementation clarifies requirements and ensures testability. It leads to better API design and higher confidence in refactoring.
+
+## 4. Engineering Processes
+
+### 4.1 Version Control and Branching
+- Use feature branches.
+- Commit often with atomic, descriptive messages.
+- Never rewrite public history.
+
+### 4.2 Code Reviews
+Code reviews are for knowledge sharing and quality assurance, not just finding bugs. They ensure consistency and help junior engineers learn from seniors.
+
+### 4.3 CI/CD (Continuous Integration/Continuous Deployment)
+Automate everything.
+- **CI:** Automatically build and test every commit to detect regressions immediately.
+- **CD:** Automate the release process to ensure reliable, repeatable deployments.
+
+## 5. Security by Design
+
+Security is not an add-on; it must be integral to the lifecycle.
+- **Least Privilege:** Components should only have the permissions they absolutely need.
+- **Input Validation:** Never trust user input. Sanitize and validate at the boundary.
+- **Dependency Management:** Regularly scan and update third-party libraries to patch vulnerabilities.
+
+## 6. Documentation
+
+Documentation is the map for future maintainers.
+- **Codebase Documentation:** Architecture diagrams, setup guides (`README.md`), and API specs.
+- **Self-Documenting Code:** Clear types and naming reduce the need for external docs.
+- **ADRs (Architecture Decision Records):** Document *why* a major technical decision was made to provide context for future teams.
+
+## Conclusion
+
+Best practices are not rigid laws but guidelines forged from decades of collective industry failure and success. Following them reduces the cognitive load on developers, minimizes bugs, and creates software that delivers value consistently over time. The goal is professional craftsmanship: writing code that you would be proud to hand over to another engineer.

scripts/e2e-parity-gate.mjs

@@ -17,7 +17,7 @@ const REQUIRED_TEST_FILES = [
   "src/core/coordinator/session-lifecycle.integration.test.ts",
   "src/core/coordinator/session-status.integration.test.ts",
   "src/core/coordinator/streaming-conversation.integration.test.ts",
-  "src/core/bridge/permission-flow.integration.test.ts",
+  "src/core/coordinator/permission-flow.integration.test.ts",
   "src/core/consumer/presence-rbac.integration.test.ts",
   "src/core/session/message-queue.integration.test.ts",
   "src/server/ws-server-flow.integration.test.ts",

src/adapters/acp/outbound-translator.test.ts

@@ -204,9 +204,7 @@ describe("translateSessionUpdate", () => {
         sessionUpdate: "tool_call_update",
         toolCallId: "call-1",
         status: "completed",
-        content: [
-          { type: "text", text: "result text" },
-        ] as unknown as AcpSessionUpdate["content"],
+        content: [{ type: "text", text: "result text" }] as unknown as AcpSessionUpdate["content"],
       };
       const result = translateSessionUpdate(update);
 

src/adapters/claude/claude-session.test.ts

@@ -823,7 +823,10 @@ describe("ClaudeSession", () => {
     await tick();
 
     // User echo → translate() returns null, consumedType=true → lines 251-264
-    ws.emit("message", JSON.stringify({ type: "user", message: { role: "user", content: "echo" } }));
+    ws.emit(
+      "message",
+      JSON.stringify({ type: "user", message: { role: "user", content: "echo" } }),
+    );
     await tick();
 
     await session.close();

src/adapters/index.ts

@@ -1,7 +1,7 @@
+export { NoopLogger, noopLogger } from "../utils/noop-logger.js";
 export { ConsoleLogger } from "./console-logger.js";
 export { DefaultGitResolver } from "./default-git-resolver.js";
 export { FileStorage } from "./file-storage.js";
 export { MemoryStorage } from "./memory-storage.js";
 export { NodeProcessManager } from "./node-process-manager.js";
 export { NodeWebSocketServer } from "./node-ws-server.js";
-export { NoopLogger, noopLogger } from "../utils/noop-logger.js";

src/adapters/opencode/opencode-adapter.test.ts

@@ -362,7 +362,11 @@ describe("OpencodeAdapter", () => {
     // by using a second controllable stream for this test.
     const encoder2 = new TextEncoder();
     let ctrl: ReadableStreamDefaultController<Uint8Array>;
-    const stream = new ReadableStream<Uint8Array>({ start(c) { ctrl = c; } });
+    const stream = new ReadableStream<Uint8Array>({
+      start(c) {
+        ctrl = c;
+      },
+    });
     connectSseSpy.mockResolvedValueOnce(stream);
 
     // Stop to allow a reconnect that uses the new stream
@@ -410,10 +414,7 @@ describe("OpencodeAdapter", () => {
 
     await defaultAdapter.connect({ sessionId: "beamcode-def" });
 
-    expect(launchSpy).toHaveBeenCalledWith(
-      "server",
-      expect.objectContaining({ port: 4096 }),
-    );
+    expect(launchSpy).toHaveBeenCalledWith("server", expect.objectContaining({ port: 4096 }));
   });
 
   it("falls back to ephemeral port when default port is in use", async () => {
@@ -428,10 +429,7 @@ describe("OpencodeAdapter", () => {
 
     await defaultAdapter.connect({ sessionId: "beamcode-def" });
 
-    expect(launchSpy).toHaveBeenCalledWith(
-      "server",
-      expect.objectContaining({ port: 54321 }),
-    );
+    expect(launchSpy).toHaveBeenCalledWith("server", expect.objectContaining({ port: 54321 }));
   });
 
   // -------------------------------------------------------------------------
@@ -513,7 +511,11 @@ describe("OpencodeAdapter", () => {
         callCount++;
         if (callCount === 1) {
           // First call: stream closes immediately → runSseLoop ends normally → line 223
-          const stream = new ReadableStream<Uint8Array>({ start(c) { c.close(); } });
+          const stream = new ReadableStream<Uint8Array>({
+            start(c) {
+              c.close();
+            },
+          });
           return Promise.resolve(stream);
         }
         // Subsequent calls: fail → triggers retry backoff → eventually exhausts

src/adapters/state-migrator.test.ts

@@ -67,9 +67,9 @@ describe("state-migrator", () => {
       messageHistory: [],
       pendingPermissions: [],
       pendingMessages: [
-        "raw ndjson string",  // string → dropped
-        objectMsg,            // plain object → kept
-        ["array", "item"],    // array → dropped
+        "raw ndjson string", // string → dropped
+        objectMsg, // plain object → kept
+        ["array", "item"], // array → dropped
       ],
       schemaVersion: 1,
     };