zcode-acp-server 0.5.1 → 0.7.0

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,KAAK,GAAG,MAAM,0BAA0B,CAAC;AAErD,OAAO,EAIL,YAAY,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IACjC,EAAE,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACzD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,WAAW,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,6BAA6B;AAC7B,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qBAAa,cAAc;IACzB,iEAAiE;IACjE,OAAO,EAAE,YAAY,GAAG,IAAI,CAAQ;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,sBAA6B;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,sBAA6B;IACtD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe;aAGf,MAAM;mBACA,OAAO,CAAC,MAAM,CAAC;QAC1B;;;;uCAI+B;qBAClB,GAAG,CAAC,SAAS,EAAE;OAE5B;IACJ;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,sBAA6B;IACjD,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,2BAAkC;IACvD;;;;OAIG;IACH,QAAQ,CAAC,YAAY,6BAAoC;IACzD,6EAA6E;IAC7E,kBAAkB,EAAE,kBAAkB,CAAM;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,iBAAwB;IACxC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,gBAAgB;gBAEb,MAAM;mBAAa,MAAM;sBAAgB,OAAO;sBAAgB,OAAO;OAC/E;IACJ,yEAAyE;IACzE,QAAQ,CAAC,aAAa,sBAA6B;IACnD;;;;;;;;;OASG;IACH,QAAQ,CAAC,qBAAqB,cAAqB;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,cAAqB;IACnD,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,sBAA6B;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,sBAA6B;IACrD,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,6EAGZ;IACJ,gEAAgE;IAChE,QAAQ,CAAC,UAAU,sBAA6B;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,sCAA6C;IACzE;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,sBAA6B;IACtD,2FAA2F;IAC3F,OAAO,CAAC,UAAU,CAAc;IAEhC,sDAAsD;IACtD,MAAM,IAAI,MAAM;IAIhB,gFAAgF;IAChF,aAAa,IAAI,YAAY;IAQ7B,0DAA0D;IAC1D,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI9C;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMvD,oEAAoE;IACpE,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAazD;;;;OAIG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IASvC;;;OAGG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;;;;OAOG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB;IAWlE,iFAAiF;IACjF,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInD;;;;;;OAMG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBrF,gFAAgF;IAChF,sBAAsB,IAAI,OAAO;IAKjC;;;;;OAKG;IACH,uBAAuB,IAAI,OAAO;IAIlC;;;;;;OAMG;IACH,uBAAuB,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI;IAgBvD,2EAA2E;IACrE,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;CAiCjF"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -64,16 +64,13 @@ export class ZcodeAcpServer {
     clients = new ClientRegistry();
     /**
      * Lightweight session summaries for the remote hub's discovery API
-     * (acp_sid → { title, updatedAt, hasActivity, unavailable }). In-memory only
-     * — the hub holds no business state and the bridge dies with its editor, so
+     * (acp_sid → { title, updatedAt, hasActivity }). In-memory only — the hub
+     * holds no business state and the bridge dies with its editor, so
      * persistence would buy nothing. Maintained by `touchSessionSummary` at
      * session registration, title set, and turn completion. `hasActivity` gates
      * the discovery payload: an editor restart auto-resumes its stored
      * placeholder, materializing an empty backend session — never-used sessions
-     * stay invisible to remote clients until first real use. `unavailable` is
-     * set by the heartbeat's availability probe (session-liveness.ts) when this
-     * backend can no longer serve the session (e.g. a restarted project took it
-     * over via a new bridge) and clears when it answers messages again.
+     * stay invisible to remote clients until first real use.
      */
     sessionSummaries = new Map();
     /** Session titles already set, to enforce set-once (acp_sid → title). */
@@ -164,8 +161,6 @@ export class ZcodeAcpServer {
             // A title only exists once the session produced content (auto-title on
             // first end_turn, or a stored title adopted on resume/load).
             hasActivity: existing?.hasActivity || title !== undefined,
-            // Keep the heartbeat-liveness verdict across mapping/title touches.
-            unavailable: existing?.unavailable,
         });
     }
     /**
@@ -182,12 +177,16 @@ export class ZcodeAcpServer {
         });
     }
     /**
-     * Best-effort workspace label for the hub discovery payload: first known
-     * session cwd, else the bridge process cwd.
+     * The bridge's project directory: first known session cwd, else the bridge
+     * process cwd (Zed spawns the server with the worktree root as cwd).
      */
-    workspaceLabel() {
+    projectCwd() {
         return this.sessionCwds.values().next().value ?? process.cwd();
     }
+    /** Best-effort workspace label for the hub discovery payload. */
+    workspaceLabel() {
+        return this.projectCwd();
+    }
     /**
      * Ensure a background-task listener is registered for the session. Idempotent
      * — returns the existing listener if already registered (covers resume/load
@@ -289,6 +288,9 @@ export class ZcodeAcpServer {
                 promptCapabilities: { image: true, audio: false, embeddedContext: false },
                 mcpCapabilities: { http: false, sse: false },
                 sessionCapabilities: { list: {}, resume: {}, fork: {} },
+                // Read-only session file access lives on the bridge's loopback /fs
+                // endpoint, hub-proxied at /api/instances/{id}/fs/* (ADR-0004).
+                _meta: { zcode: { fs: true } },
             },
             // The GLM API key is read from ~/.zcode/v2/config.json by the ZCode
             // backend subprocess; the editor never needs to supply credentials.

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AA0B/D,MAAM,OAAO,cAAc;IACzB,iEAAiE;IACjE,OAAO,GAAwB,IAAI,CAAC;IACpC,4EAA4E;IACnE,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD;;;;;;OAMG;IACM,gBAAgB,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtD;;;;;;;;;;;OAWG;IACM,eAAe,GAAG,IAAI,GAAG,EAY/B,CAAC;IACJ;;;;;OAKG;IACM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IACjD,4DAA4D;IACnD,YAAY,GAAG,IAAI,GAAG,EAAuB,CAAC;IACvD;;;;OAIG;IACM,YAAY,GAAG,IAAI,GAAG,EAAyB,CAAC;IACzD,6EAA6E;IAC7E,kBAAkB,GAAuB,EAAE,CAAC;IAC5C;;;;;;OAMG;IACM,OAAO,GAAG,IAAI,cAAc,EAAE,CAAC;IACxC;;;;;;;;;OASG;IACM,gBAAgB,GAAG,IAAI,GAAG,EAGhC,CAAC;IACJ,yEAAyE;IAChE,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IACnD;;;;;;;;;OASG;IACM,qBAAqB,GAAG,IAAI,GAAG,EAAU,CAAC;IACnD;;;;;OAKG;IACM,qBAAqB,GAAG,IAAI,GAAG,EAAU,CAAC;IACnD,sFAAsF;IAC7E,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC9C;;;;;OAKG;IACM,eAAe,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrD,6DAA6D;IACpD,OAAO,GAAG,IAAI,GAAG,EAGvB,CAAC;IACJ,gEAAgE;IACvD,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD;;;;;;OAMG;IACM,mBAAmB,GAAG,IAAI,GAAG,EAAkC,CAAC;IACzE;;;;;;;OAOG;IACM,gBAAgB,GAAG,IAAI,GAAG,EAAkB,CAAC;IACtD,2FAA2F;IACnF,UAAU,GAAG,UAAU,CAAC;IAEhC,sDAAsD;IACtD,MAAM;QACJ,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IAED,gFAAgF;IAChF,aAAa;QACX,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC;QAC9D,MAAM,GAAG,GAAG,iBAAiB,CAAC,oBAAoB,EAAE,CAAC,CAAC;QACtD,MAAM,IAAI,GAAG,mBAAmB,EAAE,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,0DAA0D;IAC1D,UAAU,CAAC,MAAc;QACvB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACrC,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,MAAc,EAAE,QAAgB;QAC9C,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAC5C,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAED,oEAAoE;IACpE,mBAAmB,CAAC,MAAc,EAAE,KAAc;QAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE;YAChC,KAAK,EAAE,KAAK,IAAI,QAAQ,EAAE,KAAK;YAC/B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,uEAAuE;YACvE,6DAA6D;YAC7D,WAAW,EAAE,QAAQ,EAAE,WAAW,IAAI,KAAK,KAAK,SAAS;SAC1D,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,iBAAiB,CAAC,MAAc;QAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,EAAE;YAChC,KAAK,EAAE,QAAQ,EAAE,KAAK;YACtB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACjE,CAAC;IAED,iEAAiE;IACjE,cAAc;QACZ,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC;IAC3B,CAAC;IAED;;;;;;;OAOG;IACH,wBAAwB,CAAC,QAAgB;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxD,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,sBAAsB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC5D,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACjD,OAAO,CAAC,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAClD,GAAG,CAAC,6CAA6C,QAAQ,EAAE,CAAC,CAAC;QAC7D,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,iFAAiF;IACjF,aAAa,CAAC,QAAgB;QAC5B,OAAO,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,gBAAgB,CAAC,QAAgB,EAAE,MAAyB;QAChE,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC1B,IAAI,CAAC;YACH,wEAAwE;YACxE,sEAAsE;YACtE,yDAAyD;YACzD,MAAM,kBAAkB,CAAC,MAAM,EAAE,GAAG,EAAE,CACpC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,MAAM,CAAC,gBAAgB,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CACjF,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,GAAG,CAAC,4CAA4C,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC9F,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,gFAAgF;IAChF,sBAAsB;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,kBAAkB,CAAC,KAAK,IAAI,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,uBAAuB;QACrB,OAAO,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC;IAC3D,CAAC;IAED;;;;;;OAMG;IACH,uBAAuB,CAAC,IAAwB;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,kBAAkB,CAAC;QACpC,MAAM,IAAI,GAAuB,EAAE,GAAG,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC;QACrD,IAAI,CAAC,EAAE,GAAG;YACR,YAAY,EAAE,GAAG,CAAC,EAAE,EAAE,YAAY,IAAI,IAAI,CAAC,EAAE,EAAE,YAAY;YAC3D,aAAa,EAAE,GAAG,CAAC,EAAE,EAAE,aAAa,IAAI,IAAI,CAAC,EAAE,EAAE,aAAa;SAC/D,CAAC;QACF,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC;QAC9C,IAAI,CAAC,WAAW,GAAG;YACjB,IAAI,EAAE,GAAG,CAAC,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC,WAAW,EAAE,IAAI;YACrD,GAAG,EAAE,GAAG,CAAC,WAAW,EAAE,GAAG,IAAI,IAAI,CAAC,WAAW,EAAE,GAAG;SACnD,CAAC;QACF,IAAI,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,GAAG,EAAE,GAAG,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC1E,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;IACjC,CAAC;IAED,2EAA2E;IAC3E,KAAK,CAAC,UAAU,CAAC,MAA6B;QAC5C,MAAM,UAAU,GAAI,MAAM,CAAC,UAAyD,IAAI,IAAI,CAAC;QAC7F,IAAI,CAAC,uBAAuB,CAAE,MAAM,CAAC,kBAAyC,IAAI,EAAE,CAAC,CAAC;QACtF,GAAG,CACD,sCAAsC,MAAM,CAAC,eAAe,EAAE;YAC5D,YAAY,UAAU,EAAE,IAAI,IAAI,SAAS,EAAE;YAC3C,aAAa,UAAU,EAAE,OAAO,IAAI,SAAS,EAAE;YAC/C,sBAAsB,IAAI,CAAC,kBAAkB,CAAC,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAC3F,CAAC;QAEF,OAAO;YACL,eAAe,EAAE,gBAAgB;YACjC,SAAS,EAAE,EAAE,GAAG,UAAU,EAAE;YAC5B,iBAAiB,EAAE;gBACjB,WAAW,EAAE,IAAI;gBACjB,kBAAkB,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE;gBACzE,eAAe,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE;gBAC5C,mBAAmB,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;gBACvD,mEAAmE;gBACnE,gEAAgE;gBAChE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE;aAC/B;YACD,oEAAoE;YACpE,oEAAoE;YACpE,uEAAuE;YACvE,kEAAkE;YAClE,WAAW,EAAE;gBACX;oBACE,EAAE,EAAE,mBAAmB;oBACvB,IAAI,EAAE,4BAA4B;oBAClC,WAAW,EACT,2HAA2H;iBAC9H;aACF;SACF,CAAC;IACJ,CAAC;CACF"}

package/docs/ARCHITECTURE.md

@@ -197,12 +197,13 @@ API only because the ZCode backend itself sends them for inference.
 
 ### `remote/` — Remote access (opt-in via `ZCODE_ACP_REMOTE=1`)
 
-| File            | Responsibility                                                                                                                                               |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `broadcast.ts`  | ClientRegistry + broadcast proxy: notify fans out to all clients; request is first-response-wins with loser `$/cancel_request`                               |
-| `config.ts`     | ENV parsing (gate, mandatory token, hub/bridge ports)                                                                                                        |
-| `endpoint.ts`   | Loopback ACP endpoint (SDK AcpServer transport, port auto-increment) + hub registration/heartbeat                                                            |
-| `hub-server.ts` | The hub singleton: token auth, instance discovery, byte-level WS proxying, heartbeat pruning, on-demand `?probe=1` liveness, idle exit, version self-upgrade |
+| File               | Responsibility                                                                                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `broadcast.ts`     | ClientRegistry + broadcast proxy: notify fans out to all clients; request is first-response-wins with loser `$/cancel_request`                               |
+| `config.ts`        | ENV parsing (gate, mandatory token, hub/bridge ports)                                                                                                        |
+| `endpoint.ts`      | Loopback ACP endpoint (SDK AcpServer transport, port auto-increment) + hub registration/heartbeat                                                            |
+| `file-endpoint.ts` | Read-only `GET /fs/list` + `GET /fs/file` on the loopback server (ADR-0004): Session Root scoping, byte/line windows, streaming                              |
+| `hub-server.ts`    | The hub singleton: token auth, instance discovery, byte-level WS proxying, heartbeat pruning, on-demand `?probe=1` liveness, idle exit, version self-upgrade |
 
 When enabled, the same `AgentApp` serves the stdio editor and a loopback
 WebSocket endpoint. Every connection (editor or remote) joins the broadcast
@@ -226,6 +227,11 @@ drops bridges that stopped registering — the fallback for hard kills — and
 on demand, so a client refresh gets an immediately-honest list with no
 background probing cost.
 
+Session file access (ADR-0004) rides the same loopback server: the bridge
+serves read-only `GET /fs/list` + `GET /fs/file` scoped to each session's cwd,
+and the hub byte-proxies them at `/api/instances/{id}/fs/*` — no new port, and
+the hub still holds no path semantics.
+
 ## Key State Machines
 
 ### Turn state

package/docs/REMOTE-CLIENTS.md

@@ -74,20 +74,34 @@ HTTP auth: `Authorization: Bearer <token>` or `?token=<token>`.
   registered bridge's loopback port and prunes unreachable ones before
   answering. A plain `GET` returns the heartbeat-based view, which can list a
   hard-killed bridge for up to the 30s heartbeat TTL.
-- `sessions[].sessionId` is the ACP session id: pass it to `session/load`
-  after connecting. `title` is adopted from the backend for resumed sessions
-  and set after a fresh session's first turn — it can still be absent for a
-  session that has never completed a turn.
-- `sessions` only lists sessions with real interaction. Editors restart into a
-  stored placeholder and materialize an empty backend session — those stay
-  hidden and appear within one heartbeat (~10s) after their first prompt (or
-  a titled resume/load).
-- `sessions` is also **availability-verified**: before every heartbeat the
-  bridge probes its idle sessions against its own backend, and a session it
-  can no longer serve (e.g. the project restarted under a newer bridge while
-  the old process leaked) is dropped from the list within one heartbeat
-  (~10s) instead of lingering as an entry that opens empty. It reappears if
-  the bridge can serve it again. Treat list membership as "openable".
+- `sessions[].sessionId` is the **ACP session id the editor uses** for that
+  conversation (placeholder ids are stable across bridges — Zed stores them
+  and the durable alias store records them). Attaching under it via
+  `session/load` puts the remote client on the same notification stream as
+  the editor tab: turns driven from either side stream live to both. A
+  conversation with no editor placeholder is advertised under its backend
+  id (`sess_…`), still loadable via pass-through resume. `title` comes from
+  the backend session store; sessions that never completed a turn have no
+  title and are not listed.
+- **Prompt echo**: when any client sends `session/prompt`, the bridge
+  broadcasts the user's text to every OTHER attached client as a
+  `user_message_chunk` (messageId prefixed `uprompt_`). Your own prompts are
+  never echoed back to you — render them locally as you send them. Without
+  this rule a turn driven from the other side arrives without the user
+  message that started it.
+- `sessions` is gated on two rules: the conversation must be **currently
+  running** (a live registration in the advertising bridge — an open editor
+  tab, or a remote attachment that ran a turn) and **accessible** (every
+  listed id resolves and resumes through that bridge). Retired conversations
+  of the project are NOT listed even though the backend store still has them
+  — the store only enriches live entries with the authoritative title and a
+  cross-bridge `updatedAt`.
+- Entries are **deduped across instances**: several bridges of the same
+  project (e.g. a leaked old process plus the current one) can all hold the
+  same live conversation under the same id; the hub keeps one copy per
+  session — the instance whose copy has the freshest `updatedAt` (i.e. the
+  bridge actually driving it). Attach to whichever instance the entry
+  appears under.
 - Poll every 3–5s. There is no push notification for registry changes yet.
 - Fields are **additive-only** across releases — ignore fields you don't know.
 
@@ -181,6 +195,43 @@ exactly:
   later. Only transport-level failures reject the request.
 - Cached ~10s server-side (same caches as the `/quota` command).
 
+## Session files (read-only)
+
+Browse and download files of a session's project — served by the bridge,
+byte-proxied by the hub, guarded by the same token as everything else
+(ADR-0004). Capability probe: `initialize` returns
+`agentCapabilities._meta.zcode.fs === true`.
+
+```text
+GET {hub}/api/instances/{id}/fs/list?sessionId=…&path=<rel>    one directory level
+GET {hub}/api/instances/{id}/fs/file?sessionId=…&path=<rel>    file bytes
+    &offset=…&length=…     byte window → 206 + Content-Range
+    &line=…&limit=…        text window (defaults 1 / 200, cap 5000)
+```
+
+- `path` resolves against the session's root cwd — the directory the session
+  was created or loaded with. Absolute paths work only when they land inside
+  it; `..` segments and symlinks pointing outside the root are rejected
+  (403).
+- `list` returns `{ root, entries: [{name, kind: "file"|"dir"|"symlink",
+size, mtime}], truncated }`. Dotfiles are included — filter client-side.
+  Entries sort dirs-first in byte order; `truncated: true` marks more than
+  2000 entries. Symlinks report placeholder stats (`size: 0`); reading
+  through one resolves and scope-checks the target.
+- `file` streams with `Content-Length` and a Content-Type inferred from the
+  extension (`application/octet-stream` fallback) — `<a download>`,
+  `<img src>`, and `fetch` streaming all work directly. `HEAD` is supported.
+- Byte and line windows are mutually exclusive (400). A line window returns
+  `text/plain` with `X-Zcode-First-Line` set to the first served line;
+  memory is O(limit), so it works on arbitrarily large logs.
+- Errors: `400` bad params · `403` unknown session / path escapes the root ·
+  `404` not found / unknown instance · `416` offset beyond EOF · `502`
+  bridge port unreachable. A `404` right after a bridge upgrade is the hub
+  self-upgrading to learn the route — retry.
+- Read-only by design, and the token remains the security boundary as
+  everywhere else; the session root contains accidents (wrong path joins),
+  not attackers.
+
 ## Slash-command handling
 
 Only the commands the bridge advertises via `available_commands_update` (plus

package/docs/REPLAY-GUIDE.md

@@ -72,31 +72,61 @@ differently:
 - `usage_update` / `available_commands_update` are session-level metadata,
   not list items.
 
-### Collapsed harness blocks (`_meta.zcode.collapsed`)
+### Collapsed harness blocks (tool_call form)
 
-Replayed user messages that are harness plumbing rather than user speech may
-carry a top-level `_meta` on the `session/update` notification:
+Replayed user messages that are harness plumbing rather than user speech are
+delivered as **`tool_call` updates, not `user_message_chunk`** — tool_call is
+the one update kind every ACP editor (Zed, JetBrains, …) renders folded by
+default, so the collapse works with zero client-side opt-in. The full text
+rides in the tool_call's `content` block (expandable); the `kind` rides the
+update's `_meta`:
 
 ```json
 {
   "sessionId": "…",
   "update": {
-    "sessionUpdate": "user_message_chunk",
-    "content": { "type": "text", "text": "This session is being continued …" },
-    "messageId": "…"
-  },
-  "_meta": { "zcode": { "collapsed": true, "kind": "context-handoff" } }
+    "sessionUpdate": "tool_call",
+    "toolCallId": "histfold_…",
+    "title": "Context handoff",
+    "kind": "other",
+    "status": "completed",
+    "content": [
+      {
+        "type": "content",
+        "content": { "type": "text", "text": "This session is being continued …" }
+      }
+    ],
+    "_meta": { "zcode": { "collapsed": true, "kind": "context-handoff" } }
+  }
 }
 ```
 
-- `kind: "context-handoff"` — the context-window continuation summary. The
-  full text is in the chunk as usual; render it **collapsed behind an expand
-  control** (e.g. a one-line label like "前序会话摘要") instead of a wall of
-  text attributed to the user.
+- `kind: "context-handoff"` — the context-window continuation summary, one
+  per compaction (a long session can carry dozens). Title: `Context handoff`.
+- `kind: "compact"` — the same compaction product on backends that tag it
+  with `semantics.kind: "compact_summary"` (session/compact, auto-compact,
+  and context-window handoff all land here). Title comes from the store's
+  own `summary.title` (observed: `Compact summary`) — so a reload shows
+  where history was compacted instead of silently missing the bridge's live
+  🔄/✓ auto-compact notices, which never enter backend history.
+- `kind: "tool-transcript"` — `Called the X tool with the following input:
+{…}\nResult of calling…` messages: tool_use/tool_result pairs the harness
+  rewrites into text on resume, one per historical tool call. Title is
+  `X · <first string value of the input JSON>` (e.g.
+  `Read · /src/main.go`), capped at 60 characters; falls back to `X tool`.
+- `kind: "task-notification"` — `<task-notification>` blocks the harness
+  injects when a background task (build, sub-agent) finishes, delivered as
+  standalone user messages. Title is the block's decoded `<summary>` line
+  (e.g. `Background command "Build release APK" completed (exit code 0)`),
+  capped at 60 characters; falls back to `Background task`.
 - Harness noise that carries no value (TodoWrite/Read usage nudges) is
-  stripped before replay — you never see it.
-- Unknown `kind`s: render collapsed too (or fall back to plain text). Ignoring
-  `_meta` entirely is always safe — the text is complete without it.
+  stripped before replay — you never see it. Synthetic messages the backend
+  marks `transcriptVisibility: "hidden"` and that fit no collapse shape
+  (plan-file references and similar plumbing) are dropped entirely.
+- Render all kinds as an ordinary collapsed tool card keyed by `toolCallId`;
+  the text is complete behind the expand. Unknown `kind`s: render collapsed
+  too. These updates never collide with live tool_call ids (they carry the
+  `histfold_` prefix).
 
 ## Turn running state (`replayMeta.turnActive` + `$/zcode/turnState`)
 

package/docs/adr/0004-session-scoped-readonly-file-access.md

@@ -0,0 +1,39 @@
+# Remote file access: session-scoped, read-only, over hub-proxied HTTP
+
+Remote clients could see session diffs and tool-call text but had no way to
+browse or download files of the project a session lives in. We decided to give
+the bridge a read-only file endpoint on its existing loopback HTTP server
+(`GET /fs/list`, `GET /fs/file`), proxied byte-for-byte by the hub at
+`GET /api/instances/{id}/fs/*` — the same proxy pattern as `/acp`. The hub
+still touches no filesystem and understands no path semantics (ADR-0002
+holds); scope checks and reads happen in the bridge, against its own
+`sessionCwds` map: a request names a `sessionId`, and the path (after
+`path.resolve` + `realpath`, defeating `..` and symlink escapes) must stay
+inside that session's root cwd. Newly created sessions are readable
+immediately because the bridge consults the in-process map, not a heartbeat
+replica.
+
+Read-only is deliberate: token holders can already drive the agent to write
+files through the permission flow, but a direct write path would widen
+token-theft damage from "control sessions" to "arbitrary filesystem writes",
+with no consistency protection against running turns. The loopback endpoint
+itself is unauthenticated, exactly like the ACP WebSocket next to it — only
+the hub (the sole public entry) enforces the token. Responses stream
+(`createReadStream` + `Content-Length`), so there is no per-request size cap;
+`offset`/`length` and `line`/`limit` (mutually exclusive) serve binary
+chunking and text windowing. `agentCapabilities._meta.zcode.fs` advertises the
+capability to clients.
+
+We rejected three alternatives. ACP extension methods (`_zcode/fs/*`) with
+base64 bodies: the SDK's WS server drops non-text frames, so a binary channel
+means bypassing the SDK transport; base64 adds 33%; and — decisively — a
+multi-MB response blocks every `session/update` behind it on the same
+WebSocket (head-of-line blocking), while HTTP gives downloads, `<img src>`,
+caching, and future `Range` support for free. The hub reading files itself:
+security-wise equivalent (the token already grants full session control), but
+the hub's registry only knows activity-gated sessions, so a fresh
+`session/new` session would have no cwd until its first turn — fixing that
+would turn the heartbeat payload from a display summary into an authoritative
+session→directory map, a second implementation of the session semantics
+ADR-0002 keeps out of the hub. External tools (filebrowser, `rclone serve`):
+separate token, port, and lifetime, with no link to sessions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcode-acp-server",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Agent Client Protocol (ACP) server bridging headless ZCode to editors like Zed and JetBrains.",
   "type": "module",
   "license": "Apache-2.0",