@0xmaxma/claude-gateway 1.5.8 → 1.6.1

package/README.md

@@ -214,6 +214,28 @@ Config lives at `~/.claude-gateway/config.json` (or set `GATEWAY_CONFIG` env var
 }
 ```
 
+### `gateway.publicUrl` (optional)
+
+The externally reachable gateway base URL. Set it manually to enable short-lived
+public image shares used by `generate_image` reference edits and `share_image`.
+The URL must end in `/gateway`; changing it requires a gateway restart.
+
+```json
+{
+  "gateway": {
+    "publicUrl": "https://vm.example.com/gateway"
+  }
+}
+```
+
+Minted share URLs have the stable form
+`https://vm.example.com/gateway/shared/TOKEN`. When `publicUrl` is set the mint
+response includes this ready-built `url`; when it is unset the response still
+returns the `token` (the share endpoint stays enabled) and callers with their own
+public base — e.g. LINE, which derives its host from the inbound webhook — build
+`<base>/shared/<token>` themselves. HTTP is accepted only for local development
+hosts such as `http://host.docker.internal:10850/gateway`.
+
 ### `session`
 
 | Field | Default | Description |

package/dist/agent/runner.d.ts

@@ -149,6 +149,23 @@ export declare class AgentRunner extends EventEmitter {
      * options are present.
      */
     private static buildImageParamsNote;
+    /**
+     * The durable slice of the composer image options — everything except
+     * `image_refs`, which is a per-turn explicit selection (#73) and must never be
+     * restored as sticky session config. Returns undefined when nothing is durable.
+     */
+    private static durableImageConfig;
+    /**
+     * The web builds image_ref/image_refs from the paths the upload endpoint
+     * returned — the ui-upload STAGING paths. promoteUiUploads then MOVES those
+     * files into per-session storage, so a note or history row built from the
+     * raw params would hand out dead paths (the agent's generate_image call
+     * fails image_ref_not_found and has to guess its way to the real file).
+     * Substitute every ref that matches a promoted staging path with its new
+     * session path; refs that were never staged (catalog refs, artifact:<id>)
+     * pass through untouched. (#74)
+     */
+    static remapImageParamsRefs(p: ImageParams | undefined, stagedPaths: readonly string[] | undefined, promotedPaths: readonly string[] | undefined): ImageParams | undefined;
     private static buildChannelXml;
     private getOrSpawnSession;
     private spawnSession;
@@ -281,6 +298,10 @@ export declare class AgentRunner extends EventEmitter {
     startLineReply(): void;
     stopLineReply(): void;
     getAgentConfig(): AgentConfig;
+    /** Configured gateway.publicUrl, or undefined. The trusted source for the
+     *  gateway's own public origin — preferred over request-derived hosts, which
+     *  a client can spoof via X-Forwarded-Host. */
+    getGatewayPublicUrl(): string | undefined;
     startTelegramReceiver(): void;
     stopTelegramReceiver(): void;
     startDiscordReceiver(): void;
@@ -357,6 +378,15 @@ export declare class AgentRunner extends EventEmitter {
      * Pop and return buffered attachment paths for a session, then clear the buffer.
      * Converts absolute paths to relative media URLs for the API response.
      */
+    /**
+     * Close a turn that died without a result (#75): drain any attachments the
+     * turn already registered (the files exist on disk — deliver them rather
+     * than leak them into the NEXT turn's reply) and record a terminal
+     * assistant row so history never ends on a dangling user message.
+     * System-initiated turns (skipUserMessage) have nothing dangling to close —
+     * only the buffer is drained.
+     */
+    private persistFailedApiTurn;
     popApiAttachments(sessionId: string): ApiAttachment[];
     private evictApiSessionMapping;
     getAgentsBaseDir(): string;

package/dist/agent/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/agent/runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAMtC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,EAAW,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAS7H,OAAO,EAA0C,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAOvF,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG7F,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAqB1C,eAAO,MAAM,oBAAoB,QAAmB,CAAC;AAErD,eAAO,MAAM,cAAc,EAAE,WAAW,EAYvC,CAAC;AAqBF,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAkD/C;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,EAAE,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAuB,GAC7C,MAAM,EAAE,CAIV;AAED,qBAAa,WAAY,SAAQ,YAAY;IAC3C,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAA4B;IAClD,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;IAC9D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD,OAAO,CAAC,SAAS,CAAoC;IAErD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IACjC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAEvC,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAsD;IACvF,OAAO,CAAC,QAAQ,CAAiC;IACjD,OAAO,CAAC,eAAe,CAAgC;IAEvD,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,gBAAgB,CAA+C;IAGvE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IAGxD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA8C;IAMhF,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;IAKhE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IAOvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAQtB;IAIH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkC;IAKlE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4E;IAGrG,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA+B;IAOjE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAO5B;IAIJ,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAG1C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAA+B;IAGrE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAoH;IAKnJ,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IAGxD,OAAO,CAAC,aAAa,CAAwC;IAG7D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAGpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IAGtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAGlC,OAAO,CAAC,aAAa,CAA6B;gBAEtC,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,MAAM;IAwBnF;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAI/C,gBAAgB,IAAI,aAAa;IAIjC,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;;OAGG;YACW,mBAAmB;IAwHjC;;;;;;OAMG;YACW,oBAAoB;IA2ElC;;;;;;;OAOG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO;IAU5D;;;;;;;;OAQG;IACH,OAAO,CAAC,oBAAoB;IAgC5B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAO5B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB,CA8BzB;IAEF;;;;;OAKG;IACH,gBAAgB,CACd,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,GACb;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAO1D,mFAAmF;IACnF,iBAAiB,CACf,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,UAAQ,GACX,IAAI,GAAG,UAAU,GAAG,MAAM;IAM7B;;;OAGG;YACW,oBAAoB;IA4NlC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,MAAM,CAAC,aAAa;IAI5B,OAAO,CAAC,iBAAiB;IAYzB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IA2GxB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAmBnC,OAAO,CAAC,MAAM,CAAC,eAAe;YA0ChB,iBAAiB;YAgDjB,YAAY;IAma1B,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIpD;;OAEG;YACW,oBAAoB;IAsBlC;;OAEG;YACW,qBAAqB;IAiBnC;;OAEG;YACW,wBAAwB;IA+CtC;;OAEG;YACW,gBAAgB;IAM9B;;OAEG;YACW,mBAAmB;IAUjC;;;OAGG;YACW,iBAAiB;IAM/B;;;OAGG;YACW,kBAAkB;IA8BhC;;OAEG;YACW,oBAAoB;IA4ClC;;;OAGG;YACW,aAAa;IAS3B;;;OAGG;YACW,cAAc;IAS5B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,qBAAqB;IAgD7B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,cAAc,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BlE;;OAEG;IACH,OAAO,CAAC,SAAS;IAWjB;;;;OAIG;IACD,OAAO,CAAC,YAAY;IAMtB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,eAAe;YAST,wBAAwB;IA2BtC,OAAO,CAAC,gBAAgB;IAexB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,gBAAgB;IAalB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B5B,iBAAiB,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI;IAQ/C,cAAc,IAAI,IAAI;IAetB,aAAa,IAAI,IAAI;IAOrB,cAAc,IAAI,WAAW;IAI7B,qBAAqB,IAAI,IAAI;IAY7B,oBAAoB,IAAI,IAAI;IAO5B,oBAAoB,IAAI,IAAI;IAY5B,mBAAmB,IAAI,IAAI;IAOrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB3B;;;;OAIG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK5F,OAAO,CAAC,sBAAsB;IAqBxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B,SAAS,IAAI,OAAO;IAIpB,kBAAkB,IAAI,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA4BzL;;;;;;;OAOG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,WAAW,CAAA;KAAE,GAC7I,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,aAAa,EAAE,CAAA;KAAE,CAAC;IAuM1D;;;;;OAKG;IACG,oBAAoB,CACxB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,EAAE;QACT,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;QACtC,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,IAAI,CAAC;QACjE,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;KAC/B,EACD,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,WAAW,CAAA;KAAE,GAC7I,OAAO,CAAC,MAAM,IAAI,CAAC;IAmOtB;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI/C;;;;OAIG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI;IAK/D;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,EAAE;IAcrD,OAAO,CAAC,sBAAsB;IAc9B,gBAAgB,IAAI,MAAM;IAI1B,WAAW,IAAI,MAAM;IAIrB,YAAY,IAAI,SAAS;IAIzB,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,WAAW,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAIhG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,UAAU,EAAE,YAAY,CAAC;IAIvH,iBAAiB,CACrB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GAC/B,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAsK/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASzC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,UAAU,EAAE,YAAY,CAAC;IAIzE,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,UAAU,EAAE,WAAW,CAAC;IAc/G,OAAO,CAAC,+BAA+B;IAsBjC,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAmB7F,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAW5I,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxE;;;;OAIG;IACG,oBAAoB,CACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,EACxC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,SAAS,EAAE;QACT,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;QACtC,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;QACnC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;KAC/B,EACD,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC;IAiItB,OAAO,CAAC,iBAAiB;IA2CzB;;;OAGG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAoBnC"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/agent/runner.ts"],"names":[],"mappings":"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"}

package/dist/agent/runner.js

@@ -94,6 +94,11 @@ const PROTECTED_WORKSPACE_FILES = [
     'IDENTITY.md', 'USER.md', 'HEARTBEAT.md',
 ];
 const MAX_API_IMAGES = 5;
+/** Extra time an api turn may keep running AFTER its soft timeout already
+ *  answered the caller (#75). The soft timeout only abandons the WAIT — the
+ *  CLI turn is still producing a result that must reach history, exactly like
+ *  the client-disconnect path. This cap bounds a genuinely hung turn. */
+const API_TIMEOUT_HARD_CAP_EXTRA_MS = 600000;
 // Hard timeout for the one-shot local `claude -p` triage during recovery
 // (Epic #195, Phase 3b). A slow/hung triage collapses to a safe notify-only.
 const RECOVERY_TRIAGE_TIMEOUT_MS = 15000;
@@ -954,13 +959,72 @@ class AgentRunner extends events_1.EventEmitter {
             typeof p.n === 'number' ? `n="${p.n}"` : '',
             p.image_ref ? `image_ref="${AgentRunner.escapeXmlAttr(p.image_ref)}"` : '',
         ].filter(Boolean);
-        if (!attrs.length)
+        const refs = (p.image_refs ?? []).filter((r) => typeof r === 'string' && r.trim().length > 0);
+        if (!attrs.length && !refs.length)
             return '';
-        return (`<image-params ${attrs.join(' ')} />\n` +
+        if (!refs.length) {
+            return (`<image-params ${attrs.join(' ')} />\n` +
+                `The user selected the image-generation options above in the composer. When the request ` +
+                `involves creating or editing an image, call the generate_image tool (action="generate") ` +
+                `using these values (pass image_ref as the "image" argument for image-to-image), then ` +
+                `deliver the returned image with your reply tool.\n`);
+        }
+        // Explicitly selected reference images (#73). Rendered as nested elements so a
+        // ref containing separators (commas, quotes) stays unambiguous.
+        const openTag = attrs.length ? `<image-params ${attrs.join(' ')}>` : '<image-params>';
+        const refLines = refs
+            .map((r, i) => `  <ref index="${i + 1}">${AgentRunner.escapeXmlAttr(r.trim())}</ref>`)
+            .join('\n');
+        const passInstruction = refs.length === 1
+            ? `Pass that single ref as the "image" argument of generate_image.`
+            : `Pass all ${refs.length} refs as the "images" argument of generate_image, in the same order.`;
+        return (`${openTag}\n${refLines}\n</image-params>\n` +
             `The user selected the image-generation options above in the composer. When the request ` +
             `involves creating or editing an image, call the generate_image tool (action="generate") ` +
-            `using these values (pass image_ref as the "image" argument for image-to-image), then ` +
-            `deliver the returned image with your reply tool.\n`);
+            `using these values, then deliver the returned image with your reply tool.\n` +
+            `The user explicitly SELECTED the reference image(s) listed above in the composer, in this order. ` +
+            `${passInstruction} Do NOT reinterpret which images they are, do NOT call list_refs to ` +
+            `second-guess an explicit selection, and do not drop any of them. ` +
+            `Do NOT open or Read the referenced files first — the image model receives the actual files; ` +
+            `reading them wastes minutes and can push the request past its timeout. Go straight to generate_image.\n`);
+    }
+    /**
+     * The durable slice of the composer image options — everything except
+     * `image_refs`, which is a per-turn explicit selection (#73) and must never be
+     * restored as sticky session config. Returns undefined when nothing is durable.
+     */
+    static durableImageConfig(p) {
+        const { image_refs: _refs, ...durable } = p;
+        return Object.keys(durable).length ? durable : undefined;
+    }
+    /**
+     * The web builds image_ref/image_refs from the paths the upload endpoint
+     * returned — the ui-upload STAGING paths. promoteUiUploads then MOVES those
+     * files into per-session storage, so a note or history row built from the
+     * raw params would hand out dead paths (the agent's generate_image call
+     * fails image_ref_not_found and has to guess its way to the real file).
+     * Substitute every ref that matches a promoted staging path with its new
+     * session path; refs that were never staged (catalog refs, artifact:<id>)
+     * pass through untouched. (#74)
+     */
+    static remapImageParamsRefs(p, stagedPaths, promotedPaths) {
+        if (!p || !stagedPaths?.length || !promotedPaths?.length)
+            return p;
+        const map = new Map();
+        for (let i = 0; i < Math.min(stagedPaths.length, promotedPaths.length); i++) {
+            const from = stagedPaths[i];
+            const to = promotedPaths[i];
+            if (from !== to)
+                map.set(from, to);
+        }
+        if (!map.size)
+            return p;
+        const remap = (r) => map.get(r) ?? r;
+        return {
+            ...p,
+            ...(p.image_ref ? { image_ref: remap(p.image_ref) } : {}),
+            ...(p.image_refs?.length ? { image_refs: p.image_refs.map(remap) } : {}),
+        };
     }
     static buildChannelXml(params) {
         const meta = params.meta ?? {};
@@ -1117,6 +1181,11 @@ class AgentRunner extends events_1.EventEmitter {
             // Auto-forward result text to channel if agent didn't call reply tool.
             let replyCalled = false;
             let replyToolUseId = null; // track id to detect failed tool calls
+            // line_image tool_use blocks re-appear across cumulative `assistant` stream
+            // snapshots (--include-partial-messages), so dedupe history inserts by the
+            // block id — otherwise one sent image lands in the transcript N times and
+            // skews the session image catalog's "image N" ordinal.
+            const seenLineImageIds = new Set();
             // Set when an interactive-menu prompt was rendered to the channel this turn,
             // so the result's plain-text auto-forward is skipped (no duplicate message).
             let menuSentThisTurn = false;
@@ -1141,6 +1210,34 @@ class AgentRunner extends events_1.EventEmitter {
                         const msg = obj['message'];
                         if (Array.isArray(msg?.content)) {
                             for (const block of msg.content) {
+                                // LINE sends images through its own line_image tool (not the reply
+                                // tool's `files`), so capture those sends into history too — the
+                                // web transcript and the session image catalog key off mediaFiles.
+                                if (block.type === 'tool_use' && block.name === 'mcp__gateway__line_image') {
+                                    const lineBlockId = block['id'];
+                                    const dedupeKey = typeof lineBlockId === 'string' ? lineBlockId : '';
+                                    // Skip if this tool_use block was already persisted this turn
+                                    // (cumulative assistant snapshots re-emit completed blocks).
+                                    if (dedupeKey && seenLineImageIds.has(dedupeKey))
+                                        continue;
+                                    const imgPath = typeof block.input?.['image'] === 'string' ? block.input['image'] : '';
+                                    const mediaRootLine = path.join(this.agentsBaseDir, this.agentConfig.id, 'media') + path.sep;
+                                    const lineMedia = toRelMediaFiles(imgPath ? [imgPath] : [], mediaRootLine);
+                                    if (lineMedia.length) {
+                                        if (dedupeKey)
+                                            seenLineImageIds.add(dedupeKey);
+                                        const channelSrcLine = this.channelSourceMap.get(mapKey) ?? 'line';
+                                        this.historyDb.insertMessage({
+                                            chatId: `${channelSrcLine}-${mapKey}`,
+                                            sessionId: actualSessionId,
+                                            source: channelSrcLine,
+                                            role: 'assistant',
+                                            content: '',
+                                            mediaFiles: lineMedia,
+                                            ts: Date.now(),
+                                        });
+                                    }
+                                }
                                 if (block.type === 'tool_use' && block.name === replyToolName && !replyCalled) {
                                     replyCalled = true;
                                     replyToolUseId = block['id'] ?? null;
@@ -1333,6 +1430,7 @@ class AgentRunner extends events_1.EventEmitter {
                         }
                         replyCalled = false; // reset for next turn
                         replyToolUseId = null;
+                        seenLineImageIds.clear();
                         menuSentThisTurn = false;
                         menuPromptTextThisTurn = '';
                         // In pty-shell mode, a `result` fires after every Claude API sub-turn
@@ -1947,6 +2045,12 @@ class AgentRunner extends events_1.EventEmitter {
     getAgentConfig() {
         return { ...this.agentConfig };
     }
+    /** Configured gateway.publicUrl, or undefined. The trusted source for the
+     *  gateway's own public origin — preferred over request-derived hosts, which
+     *  a client can spoof via X-Forwarded-Host. */
+    getGatewayPublicUrl() {
+        return this.gatewayConfig.gateway.publicUrl;
+    }
     startTelegramReceiver() {
         if (this.receiver?.isRunning())
             return;
@@ -2089,6 +2193,9 @@ class AgentRunner extends events_1.EventEmitter {
         const finalMediaFiles = opts.mediaFiles?.length
             ? await promoteUiUploads(this.agentsBaseDir, this.agentConfig.id, sessionId, opts.mediaFiles, this.logger)
             : undefined;
+        // Refs built from staging paths must follow the files to their promoted
+        // location — see remapImageParamsRefs (#74).
+        const imageParams = AgentRunner.remapImageParamsRefs(opts.imageParams, opts.mediaFiles, finalMediaFiles);
         // Resolve media files to absolute paths for file-path based image passing
         // (same pattern as Telegram — Claude Code reads files via Read tool instead of base64 inline)
         const imagePaths = finalMediaFiles?.length ? this.resolveMediaPaths(finalMediaFiles) : [];
@@ -2112,10 +2219,18 @@ class AgentRunner extends events_1.EventEmitter {
                 role: 'user',
                 content: message,
                 mediaFiles: finalMediaFiles?.length ? finalMediaFiles : undefined,
+                // Display-only (#74): lets the UI show which earlier images this turn
+                // referenced after a reload. The generation path reads the refs from the
+                // image-params note, never from here.
+                imageRefs: imageParams?.image_refs?.length ? imageParams.image_refs : undefined,
                 ts: apiUserTs,
             });
         }
         this.pendingApiSessions.add(sessionId);
+        // A previous turn that died (hard timeout, crash) may have left attachments
+        // buffered under this session — they belong to THAT turn; never let them
+        // ride along on this one (#75).
+        this.pendingApiAttachments.delete(sessionId);
         session.touch();
         // Image paths only work when allowTools:true — Claude needs the Read tool to access them
         const allowTools = opts.allowTools ?? false;
@@ -2135,14 +2250,16 @@ class AgentRunner extends events_1.EventEmitter {
         }
         // Build channel XML with image_path attribute (like Telegram) for first image
         const imageAttr = effectiveImagePaths.length ? ` image_path="${AgentRunner.escapeXmlAttr(effectiveImagePaths[0])}"` : '';
-        const imageParamsNote = opts.imageParams ? AgentRunner.buildImageParamsNote(opts.imageParams) : '';
+        const imageParamsNote = imageParams ? AgentRunner.buildImageParamsNote(imageParams) : '';
         // Persist the composer image options to session meta so the web can restore the
         // selection on reload (SessionMeta.imageConfig). Only when the send carries them
         // (the web sends image_params on first-set/change), so this holds the latest.
+        // image_refs are per-turn and deliberately excluded (#73).
         // Channel is 'api' here (api sessions live under api-<chatId>). Best-effort.
-        if (opts.imageParams) {
+        const durableImageConfig = imageParams ? AgentRunner.durableImageConfig(imageParams) : undefined;
+        if (durableImageConfig) {
             this.sessionStore
-                .updateSessionMeta(this.agentConfig.id, chatId, sessionId, { imageConfig: opts.imageParams }, 'api')
+                .updateSessionMeta(this.agentConfig.id, chatId, sessionId, { imageConfig: durableImageConfig }, 'api')
                 .catch(() => { });
         }
         const channelXml = `<channel source="api" chat_id="${chatId}" session_id="${sessionId}" ts="${new Date().toISOString()}"${imageAttr}>\n` +
@@ -2183,11 +2300,17 @@ class AgentRunner extends events_1.EventEmitter {
                 resolve({ text: result.trim(), attachments });
             };
             const fail = (err) => {
+                // Terminal close for a turn that produced no result (#75): record it so
+                // history does not end on a dangling user message, and drain the
+                // attachment buffer so nothing leaks into the next turn.
+                this.persistFailedApiTurn(chatId, sessionId, err, opts.skipUserMessage);
                 cleanup();
-                reject(err);
+                reject(err); // no-op when the soft timeout already rejected
             };
             const cleanup = () => {
                 clearTimeout(globalTimer);
+                if (hardCapTimer)
+                    clearTimeout(hardCapTimer);
                 if (quietTimer)
                     clearTimeout(quietTimer);
                 session.off('output', onOutput);
@@ -2239,9 +2362,17 @@ class AgentRunner extends events_1.EventEmitter {
                     /* non-JSON stdout line */
                 }
             };
+            // Soft timeout (#75): unblock the caller now, but KEEP the output listener
+            // attached — a turn finishing moments late must still persist its result
+            // and attachments, mirroring the client-disconnect path. The hard cap
+            // bounds a genuinely hung turn.
+            let hardCapTimer;
             const globalTimer = setTimeout(() => {
-                session.setProcessing(false);
-                fail(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT' }));
+                reject(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT' }));
+                hardCapTimer = setTimeout(() => {
+                    session.setProcessing(false);
+                    fail(Object.assign(new Error('Agent response timed out.'), { code: 'TIMEOUT' }));
+                }, API_TIMEOUT_HARD_CAP_EXTRA_MS);
             }, opts.timeoutMs);
             session.on('output', onOutput);
             session.setProcessing(true);
@@ -2273,6 +2404,9 @@ class AgentRunner extends events_1.EventEmitter {
         const finalMediaFilesStream = opts.mediaFiles?.length
             ? await promoteUiUploads(this.agentsBaseDir, this.agentConfig.id, sessionId, opts.mediaFiles, this.logger)
             : undefined;
+        // Refs built from staging paths must follow the files to their promoted
+        // location — see remapImageParamsRefs (#74).
+        const imageParamsStream = AgentRunner.remapImageParamsRefs(opts.imageParams, opts.mediaFiles, finalMediaFilesStream);
         // Resolve media files to absolute paths for file-path based image passing
         const imagePathsStream = finalMediaFilesStream?.length ? this.resolveMediaPaths(finalMediaFilesStream) : [];
         if (!opts.skipUserMessage) {
@@ -2291,14 +2425,32 @@ class AgentRunner extends events_1.EventEmitter {
                 role: 'user',
                 content: message,
                 mediaFiles: finalMediaFilesStream?.length ? finalMediaFilesStream : undefined,
+                // Display-only (#74): lets the UI show which earlier images this turn
+                // referenced after a reload. The generation path reads the refs from the
+                // image-params note, never from here.
+                imageRefs: imageParamsStream?.image_refs?.length ? imageParamsStream.image_refs : undefined,
                 ts: streamUserTs,
             });
         }
         this.pendingApiSessions.add(sessionId);
+        // A previous turn that died (hard timeout, crash) may have left attachments
+        // buffered under this session — they belong to THAT turn; never let them
+        // ride along on this one (#75).
+        this.pendingApiAttachments.delete(sessionId);
         session.touch();
         const buffer = [];
         let settled = false;
         let clientGone = false;
+        // onError must fire at most once per turn. The soft timeout notifies the
+        // client directly (below) WITHOUT setting `settled`, so the later hard-cap
+        // fail() would otherwise call onError a second time.
+        let errorNotified = false;
+        const notifyError = (err) => {
+            if (errorNotified)
+                return;
+            errorNotified = true;
+            callbacks.onError(err);
+        };
         // Track partial message text for delta computation (--include-partial-messages)
         let lastPartialText = '';
         // Accumulate tool_use blocks from stream_event (content_block_start → delta → stop)
@@ -2338,10 +2490,17 @@ class AgentRunner extends events_1.EventEmitter {
                 return;
             settled = true;
             cleanup();
-            callbacks.onError(err);
+            // Terminal close for a turn that produced no result (#75): record it so
+            // history does not end on a dangling user message (the web reads that
+            // state as "still thinking" and spins forever), and drain the attachment
+            // buffer so nothing leaks into the next turn.
+            this.persistFailedApiTurn(chatId, sessionId, err, opts.skipUserMessage);
+            notifyError(err);
         };
         const cleanup = () => {
             clearTimeout(globalTimer);
+            if (hardCapTimer)
+                clearTimeout(hardCapTimer);
             session.off('output', onOutput);
             this.pendingApiSessions.delete(sessionId);
         };
@@ -2422,9 +2581,26 @@ class AgentRunner extends events_1.EventEmitter {
                 /* non-JSON stdout line */
             }
         };
+        // Soft timeout (#75): tell the SSE client now, but KEEP the output listener
+        // attached — exactly like onClientDisconnect — so a turn that finishes a few
+        // seconds past the budget still lands in history with its attachments
+        // (observed: 304s image turn vs 300s budget → image generated, reply lost,
+        // spinner stuck). The hard cap bounds a genuinely hung turn.
+        let hardCapTimer;
         const globalTimer = setTimeout(() => {
-            session.setProcessing(false);
-            fail(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT' }));
+            clientGone = true;
+            try {
+                notifyError(Object.assign(new Error('Agent response timeout'), { code: 'TIMEOUT' }));
+            }
+            catch { /* client already gone */ }
+            // The session stays in-flight (pendingApiSessions) until the hard cap so a
+            // retry on the SAME session_id gets a 409 CONFLICT rather than interleaving
+            // with the subprocess that is still processing this turn. This lock is
+            // intentionally held for the whole soft→hard window (see API.md §409).
+            hardCapTimer = setTimeout(() => {
+                session.setProcessing(false);
+                fail(Object.assign(new Error('Agent response timed out.'), { code: 'TIMEOUT' }));
+            }, API_TIMEOUT_HARD_CAP_EXTRA_MS);
         }, opts.timeoutMs);
         session.on('output', onOutput);
         // Image paths only work when allowTools:true — Claude needs the Read tool to access them
@@ -2445,13 +2621,17 @@ class AgentRunner extends events_1.EventEmitter {
         }
         // Build channel XML with image_path attribute (like Telegram) for first image
         const imageAttrStream = effectiveImagePathsStream.length ? ` image_path="${AgentRunner.escapeXmlAttr(effectiveImagePathsStream[0])}"` : '';
-        const imageParamsNoteStream = opts.imageParams ? AgentRunner.buildImageParamsNote(opts.imageParams) : '';
+        const imageParamsNoteStream = imageParamsStream ? AgentRunner.buildImageParamsNote(imageParamsStream) : '';
         // Persist composer image config to session meta (SessionMeta.imageConfig) so the
         // web restores the selection on reload. This is the streaming path the web uses.
+        // image_refs are per-turn and deliberately excluded (#73).
         // Channel 'api' — api sessions live under api-<chatId>. Best-effort.
-        if (opts.imageParams) {
+        const durableImageConfigStream = imageParamsStream
+            ? AgentRunner.durableImageConfig(imageParamsStream)
+            : undefined;
+        if (durableImageConfigStream) {
             this.sessionStore
-                .updateSessionMeta(this.agentConfig.id, chatId, sessionId, { imageConfig: opts.imageParams }, 'api')
+                .updateSessionMeta(this.agentConfig.id, chatId, sessionId, { imageConfig: durableImageConfigStream }, 'api')
                 .catch(() => { });
         }
         const channelXml = `<channel source="api" chat_id="${chatId}" session_id="${sessionId}" ts="${new Date().toISOString()}"${imageAttrStream}>\n` +
@@ -2483,6 +2663,33 @@ class AgentRunner extends events_1.EventEmitter {
      * Pop and return buffered attachment paths for a session, then clear the buffer.
      * Converts absolute paths to relative media URLs for the API response.
      */
+    /**
+     * Close a turn that died without a result (#75): drain any attachments the
+     * turn already registered (the files exist on disk — deliver them rather
+     * than leak them into the NEXT turn's reply) and record a terminal
+     * assistant row so history never ends on a dangling user message.
+     * System-initiated turns (skipUserMessage) have nothing dangling to close —
+     * only the buffer is drained.
+     */
+    persistFailedApiTurn(chatId, sessionId, err, skipUserMessage) {
+        const attachments = this.popApiAttachments(sessionId);
+        if (skipUserMessage)
+            return;
+        const failTs = Date.now();
+        const content = `\u26a0\ufe0f ${err.message}`;
+        this.sessionStore
+            .appendMessage(this.agentConfig.id, sessionId, { role: 'assistant', content, ts: failTs })
+            .catch(() => { });
+        this.historyDb.insertMessage({
+            chatId: `api-${chatId}`,
+            sessionId,
+            source: 'api',
+            role: 'assistant',
+            content,
+            mediaFiles: attachments.length ? attachments.map((a) => `media/${a.relPath}`) : undefined,
+            ts: failTs,
+        });
+    }
     popApiAttachments(sessionId) {
         const paths = this.pendingApiAttachments.get(sessionId) ?? [];
         this.pendingApiAttachments.delete(sessionId);