✨ Keep a REPL execution's chat beside its entries (#883, PR 2 of 2)

.agents/architecture-rules.md

@@ -17,7 +17,7 @@ the system itself; this file governs how new architecture is designed.
 8. Feature-specific runtime APIs stay with their feature package and are not collected into a central runner context.
 9. Immutable view data flows down and typed semantic actions flow up; the root alone owns route intent, selection and rebuildable application state.
 10. A component lifetime may own a node; a render body may not create or own one.
-11. View data and placement cross the direct parent-child boundary and no other.
+11. View data and layout cross the direct parent-child boundary and no other.
 12. Normalized host input is decided once and dispatched through the target's own ancestry; a host names a target and an event shape, never an action. Text is its own event shape carrying what the terminal decoded, and a modified chord is dropped whole rather than read off its physical key code.
 13. Freedom alone owns focus; an overlay is a mounted branch, not a second tree.
 14. Keyed descriptions reconcile into one mounted tree; validate the complete desired set before mutating any of it.
@@ -28,6 +28,15 @@ the system itself; this file governs how new architecture is designed.
 19. Renderer output is copied out of the engine before returning, and a refused frame is redrawn on a renderer rebuilt for that frame's dimensions without changing selection, focus, actions or the frame itself.
 20. A contextual adapter owns terminal modes, listeners and readers, registers their release before taking them, and restores them exactly once on every exit.
 21. A narrow surface displays the one route selected; every other surface is absent from the frame, its map and its targets rather than hidden within them.
+23. Use methods on an owned handle for operations tied to that instance.
+24. Use a Context to select a scoped service; capture it for any lifetime that requires a fixed provider.
+25. Use middleware when per-call interception or transformation is an intended extension point.
+
+Rules 23–25 choose the API by ownership and intended composition. A captured
+service keeps provider selection fixed for its consumer's lifetime; its mutable
+configuration still follows that service's own update contract. A Context
+selects a trusted service, while authorization, durable identity,
+reconciliation and canonical outcomes stay with their owners.
 
 The Architect applies these rules without another approval when they settle a
 design. A new concept, ambiguous fit, conflict or proposed exception returns to

.agents/component-descriptions.md

@@ -55,7 +55,7 @@ structured fields cannot provide, not as a second reference entry.
 
 9. Keep behavior that changes use.
 
-   Activation conditions, placement rules, scope, transport choices, failure
+   Activation conditions, structural rules, scope, transport choices, failure
    behavior and preflight-only forms belong when they determine what an author
    writes or observes.
 

AGENTS.md

@@ -459,8 +459,9 @@ the corpus or enabling in-shard concurrency is not an answer to a miss.
     job withholds the required `green` check until CI has proven `main`'s exact
     current head. Repairing it is a pull request a maintainer labels
     `ci-main-red-fix`, which runs `composability` in the gate's place.
-15. State shared across loaded copies uses stable, namespaced names: plain
-    structural values for composition data and a contextual Api for operations.
+15. State shared across loaded copies uses stable, namespaced names. Use owned
+    handles for instance operations, Context for scoped service selection, and
+    contextual Api middleware for intended per-call composition.
     Security enforcement, durable identity, and reconciliation never trust
     replaceable context state.
 16. An event listener an Effection operation installs has that operation's

packages/acp/mod.ts

@@ -10,7 +10,7 @@
  *
  * A harness that needs several independent providers in sibling scopes uses
  * `useAcpxProvider()` instead, which is the same operations without the Agent
- * install. Everything else here — the permission bridge, session placement,
+ * install. Everything else here — the permission bridge, session setup,
  * turn consumption, and the queues serializing them — is implementation.
  */
 
@@ -23,9 +23,9 @@ export { createAcpxProvider } from "./src/provider.ts";
 export type {
   AcpMcpServer,
   AcpxProviderDependencies,
-  AcpxSessionContext,
+  AcpxSessionRequest,
   AcpxSessionIdentity,
-  AcpxSessionPlacement,
+  AcpxSessionDetails,
   AcpxSessionPolicy,
   SessionRouteContext,
 } from "./src/provider.ts";
@@ -86,6 +86,7 @@ export type { AcpxRetainedSession, AcpxSessionStore } from "./src/session-store.
 
 export {
   AcpxPartitionError,
+  AcpxSessionPolicyError,
   createPartitionedAcpxProvider,
   useAcpxProvider,
 } from "./src/provider.ts";

packages/acp/src/adapter-snapshots.ts

@@ -682,7 +682,7 @@ export function carriesEmbeddedAdapter(adapters: EmbeddedAdapters, agentName: st
  * preparation would materialize an adapter and then run whatever `npx` resolved.
  *
  * Preparation happens at the first point the provider would run that command,
- * which is its availability probe — earlier than a `<Session>` placement, and
+ * which is its availability probe — earlier than a `<Session>` request, and
  * earlier than any turn. A snapshot that cannot prove itself refuses the agent
  * there rather than surfacing later as an adapter that would not start.
  *