@fastagent-sh/fastagent 0.17.0 → 0.18.0

package/dist/agent.d.ts

@@ -19,6 +19,17 @@ export interface Prompt {
 export interface Scope {
     /** Opaque session anchor: turns of the same logical conversation MUST reuse the same value. */
     session: string;
+    /** EXTENSION (SPEC §8): the session this one branched from — a channel sets it when the place it
+     *  is invoking for was born out of another place (a thread opened in a room). Read ONLY when
+     *  `session` does not exist yet: an engine that understands it seeds the NEW session from the
+     *  parent once, at creation; after that the field is ignored, and an engine that does not
+     *  understand it ignores it entirely (the session starts empty, yesterday's behavior). */
+    parentSession?: string;
+    /** EXTENSION (SPEC §8): opaque markers that MAY locate the branch point inside `parentSession` —
+     *  e.g. platform message ids its transcript embeds. Best-effort by design: the first marker found
+     *  in the parent's transcript wins, and no match falls back to the parent's present. Meaningless
+     *  without `parentSession`. */
+    branchHints?: string[];
 }
 export type AgentEvent = {
     type: "text";

package/dist/channels/agentcore.d.ts

@@ -54,6 +54,15 @@ export type AgentcoreEnvelope = {
  *  "channels with replay re-run it" true rather than aspirational. */
  | {
     kind: "checkpoint";
+}
+/** The deploy driver's post-deploy verification (relayed by the forwarder's reserved
+ *  `/__fastagent/probe` path, which answers on EVERY forwarder topology — schedule-only URLs
+ *  refuse ordinary public traffic). Runs restore + channel construction end to end and answers a
+ *  TRANSPORT-200 structured verdict `{ ok, error? }`: the ordinary webhook path folds a non-200
+ *  transport into an opaque 502 at the forwarder, which would strip exactly the diagnostics this
+ *  probe exists to carry. */
+ | {
+    kind: "probe";
 });
 /** The webhook envelope's reply: the channel's real HTTP response, ridden inside a transport-200
  *  body so the forwarder can re-emit it verbatim (see the module header on AgentCore's 424 folding). */
@@ -63,8 +72,13 @@ export interface WebhookReply {
     bodyB64: string;
 }
 export interface AgentcoreAdapterOptions {
-    /** The serving routes a direct deployment would mount (channels or the builtin invoke + health). */
-    routes: Routes;
+    /** The serving routes a direct deployment would mount (channels or the builtin invoke + health).
+     *  The serving path passes a LAZY factory: channel construction loads channel state and replays
+     *  durable turn intent, so on AgentCore it must not run until the state root is authoritative —
+     *  which happens at the first envelope's `stateSync.ready()` (the restore URLs only an envelope
+     *  carries), never at boot, where the mount is pre-restore (empty after every version update).
+     *  An eager `Routes` value remains supported for wirings whose state root is already durable. */
+    routes: Routes | (() => Promise<Routes> | Routes);
     agent: Agent;
     /** Where the forwarder URL from envelopes is persisted for the wake-alarm sink (the state root). */
     stateRoot: string;

package/dist/channels/agentcore.js

@@ -55,7 +55,28 @@ function secretMatches(actual, expected) {
  */
 export function agentcoreRoutes(options) {
     const { routes, agent, stateRoot, isBusy, fire, stateSync, ingressSecret, onStateReady } = options;
-    const dispatch = router(routes);
+    // Lazy channel construction (see AgentcoreAdapterOptions.routes) — resolved ONCE per process, on
+    // the first trusted envelope after the state root is authoritative, and the outcome is cached
+    // EITHER WAY. Success: the same resident channels a direct host keeps. Failure too: construction
+    // is an ACTIVATION with side effects — loadChannels builds every healthy channel (starting its
+    // queues and replaying durable turn intent) before reporting another module's failure — and there
+    // is no cleanup contract to unwind it, so re-running it per envelope could replay the same
+    // recovered turn concurrently. The first rejection is therefore the process's answer: every later
+    // envelope fails with the same message (visible each time), the retry boundary is a fresh session
+    // (which scale-to-zero provides naturally), and the deploy driver's probe catches deterministic
+    // failures at deploy time.
+    let dispatchP;
+    const resolveDispatch = () => {
+        if (!dispatchP) {
+            // The factory runs INSIDE the chain: a synchronous throw must land in the cached rejection,
+            // not escape before `dispatchP` is assigned (which would silently re-run the activation).
+            dispatchP = Promise.resolve()
+                .then(() => (typeof routes === "function" ? routes() : routes))
+                .then(router);
+            dispatchP.catch(() => { }); // observed here so the CACHED rejection is never "unhandled"
+        }
+        return dispatchP;
+    };
     const invokeHandler = createInvokeHandler(agent);
     // Snapshot on the 0-in-flight edge: webhook channels ACK fast and finish the turn in the
     // background, so "the request returned" is NOT when the state root settles.
@@ -75,7 +96,7 @@ export function agentcoreRoutes(options) {
             return text("invalid json\n", 400);
         }
         if (envelope === null || typeof envelope !== "object" || typeof envelope.kind !== "string") {
-            return text('need { "kind": "webhook" | "schedule-fire" | "invoke" | "wake-poke" | "checkpoint", ... }\n', 400);
+            return text('need { "kind": "webhook" | "schedule-fire" | "invoke" | "wake-poke" | "checkpoint" | "probe", ... }\n', 400);
         }
         // AUTHENTICATION BOUNDARY. `InvokeAgentRuntime` is an ordinary IAM action, so "reached this
         // handler" proves nothing about the sender. Only an envelope carrying the shared secret is the
@@ -113,7 +134,7 @@ export function agentcoreRoutes(options) {
                 stateSync.use(envelope.state);
             }
             else if (envelope.kind !== "invoke" && !stateSync.configured() && !warnedUnsnapshotted) {
-                // webhook/schedule-fire/wake-poke reach us ONLY through the forwarder, which always mints the
+                // webhook/schedule-fire/wake-poke/probe reach us ONLY through the forwarder, which mints the
                 // pair. Missing = a broken/stale topology whose state dies at the next deploy: say so, loudly,
                 // once per process (a direct `invoke` legitimately has none — its session storage is its own).
                 warnedUnsnapshotted = true;
@@ -124,6 +145,11 @@ export function agentcoreRoutes(options) {
             }
             catch (e) {
                 log.error(`[agentcore] state restore failed: ${String(e)}`);
+                // The probe is the deploy driver's verification channel: its diagnostics must survive the
+                // forwarder, which folds a non-200 transport into an opaque 502 — so for it the failure
+                // rides a transport-200 structured verdict; every other kind keeps the plain 503.
+                if (envelope.kind === "probe")
+                    return json({ ok: false, error: `state restore failed: ${String(e)}` }, 200);
                 return text(`state restore failed: ${String(e)}\n`, 503);
             }
         }
@@ -134,6 +160,26 @@ export function agentcoreRoutes(options) {
             stateReadyFired = true;
             onStateReady();
         }
+        // PROCESS INITIALIZATION, kind-independent: the (lazy) channels are constructed on the first
+        // trusted ingress after the state root became authoritative — whichever kind carries it, so a
+        // cold start woken by a schedule fire or an alarm poke still replays checkpointed turn intent.
+        // Two deliberate exceptions: `checkpoint` must push state even when a channel is broken, and a
+        // public `invoke` runs in its own isolated storage — constructing against THAT root would cache
+        // pre-restore emptiness for the ingress session. Failure policy is per kind below: webhook and
+        // wake-poke fail their request (503), the probe reports it structurally, and a schedule fire
+        // proceeds — cron does not consume channels, and letting an unrelated channel misconfiguration
+        // silence the clock would turn one fault into two (the error is logged here either way).
+        let constructionError;
+        let dispatch;
+        if (trusted && envelope.kind !== "checkpoint" && envelope.kind !== "invoke") {
+            try {
+                dispatch = await resolveDispatch();
+            }
+            catch (e) {
+                constructionError = String(e);
+                log.error(`[agentcore] channel construction failed: ${constructionError}`);
+            }
+        }
         switch (envelope.kind) {
             case "webhook": {
                 const { method, path, query, headers, bodyB64 } = envelope;
@@ -154,6 +200,10 @@ export function agentcoreRoutes(options) {
                         ? Buffer.from(bodyB64, "base64")
                         : undefined,
                 });
+                // A construction failure is the request's failure (503 through the forwarder, so the
+                // platform retries and the operator sees the message), never a silently-empty channel.
+                if (!dispatch)
+                    return text(`channel construction failed: ${constructionError ?? "unavailable"}\n`, 503);
                 const response = await dispatch(inner);
                 // Buffer the channel's ACK (webhook ACKs are small by design — the turn itself runs
                 // fire-and-forget) and ride it inside the transport reply, byte-exact.
@@ -218,9 +268,21 @@ export function agentcoreRoutes(options) {
             }
             case "wake-poke": {
                 // The poke's job is DONE by arriving: the invocation woke (or kept awake) the container, and
-                // the wake pump (boot drain + 30s poll) fires whatever is due. Nothing to dispatch.
+                // the wake pump (boot drain + 30s poll) fires whatever is due. Nothing to dispatch — the
+                // initialization above already resolved construction (replaying checkpointed turn intent),
+                // and its failure is this request's failure so the alarm's log line names it.
+                if (constructionError !== undefined)
+                    return text(`channel construction failed: ${constructionError}\n`, 503);
                 return json({ ok: true }, 200);
             }
+            case "probe": {
+                // The structured verdict (transport-200 — see the envelope doc): the deploy driver reads it
+                // through the forwarder's reserved path, so the error text survives the hop that turns any
+                // non-200 transport into an opaque 502.
+                return json(constructionError === undefined
+                    ? { ok: true }
+                    : { ok: false, error: `channel construction failed: ${constructionError}` }, 200);
+            }
             case "invoke": {
                 // Reuse the HTTP channel's handler wholesale (SSE, cancellation, backpressure) by handing it
                 // the shape it already validates — one protocol, one implementation.

package/dist/channels/feishu/card.d.ts

@@ -3,16 +3,24 @@
  * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
  * the card DSL is data-in → string-out and testable without the pump.
  *
- * The preview is ONE markdown element (`element_id` below) inside a card with `streaming_mode` on:
- * the pump PUTs full-text snapshots at that element (feishu-api.ts `updateCardElement`) and the client
- * renders the typewriter effect. Settling replaces the whole entity (`updateCard`) with the same
- * element, `streaming_mode` off — one write flips content and mode together.
+ * The streaming card is TWO markdown elements: `process` (the volatile block — thinking tail, tool
+ * lines, retry notice) and `answer` (append-only). The pump PUTs full-text snapshots per element
+ * (feishu-api.ts `updateCardElement`) and the client renders the typewriter effect. The split is the
+ * prefix-stability rule made structural: the client animates an element's update only when the old
+ * text is a PREFIX of the new — otherwise it re-types everything after the first divergent character.
+ * The process block's head changes every frame (a sliding thinking tail, `…`→`✓` status flips), so
+ * sharing one element with the answer re-typed the whole card once a second; two elements confine the
+ * churn to the small process block and keep the answer's typewriter smooth. Settling replaces the
+ * whole entity (`updateCard`) with the answer element alone, `streaming_mode` off — one write flips
+ * content and mode together and drops the process block.
  *
  * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
  * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
  */
-/** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
+/** The append-only answer element's id — shared by create (card.ts) and update (preview.ts). */
 export declare const ANSWER_ELEMENT_ID = "answer";
+/** The volatile process element's id (thinking tail + tool lines + retry notice; live-only). */
+export declare const PROCESS_ELEMENT_ID = "process";
 /** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
 export declare const CARD_MARKDOWN_MAX_BYTES: number;
 /**
@@ -23,10 +31,13 @@ export declare const CARD_MARKDOWN_MAX_BYTES: number;
  * emphasis/heading/list markers removed.
  */
 export declare function cardSummary(markdown: string): string;
-/** The live-preview card entity: streaming on, seeded with the placeholder/first view. */
-export declare function streamingCardJson(initial: string): string;
-/** The settled card: final markdown, streaming off (stops the client's streaming affordance), plus
- *  the answer-derived summary so the chat list / notification shows the reply, not "[Card]". */
+/** The live-preview card entity: streaming on, the process element seeded with the placeholder/queue
+ *  status and the answer element seeded EMPTY (the platform accepts an empty markdown element; it
+ *  renders zero-height until the first answer snapshot lands as a clean prefix extension of ""). */
+export declare function streamingCardJson(initialProcess: string): string;
+/** The settled card: final markdown alone (the process block was preview-only), streaming off (stops
+ *  the client's streaming affordance), plus the answer-derived summary so the chat list / notification
+ *  shows the reply, not "[Card]". */
 export declare function finalCardJson(markdown: string): string;
 /** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
 export declare function cardEntityContent(cardId: string): string;

package/dist/channels/feishu/card.js

@@ -3,17 +3,25 @@
  * final card, and the message content that mounts a card entity into a chat. Kept out of preview.ts so
  * the card DSL is data-in → string-out and testable without the pump.
  *
- * The preview is ONE markdown element (`element_id` below) inside a card with `streaming_mode` on:
- * the pump PUTs full-text snapshots at that element (feishu-api.ts `updateCardElement`) and the client
- * renders the typewriter effect. Settling replaces the whole entity (`updateCard`) with the same
- * element, `streaming_mode` off — one write flips content and mode together.
+ * The streaming card is TWO markdown elements: `process` (the volatile block — thinking tail, tool
+ * lines, retry notice) and `answer` (append-only). The pump PUTs full-text snapshots per element
+ * (feishu-api.ts `updateCardElement`) and the client renders the typewriter effect. The split is the
+ * prefix-stability rule made structural: the client animates an element's update only when the old
+ * text is a PREFIX of the new — otherwise it re-types everything after the first divergent character.
+ * The process block's head changes every frame (a sliding thinking tail, `…`→`✓` status flips), so
+ * sharing one element with the answer re-typed the whole card once a second; two elements confine the
+ * churn to the small process block and keep the answer's typewriter smooth. Settling replaces the
+ * whole entity (`updateCard`) with the answer element alone, `streaming_mode` off — one write flips
+ * content and mode together and drops the process block.
  *
  * Budget: a card entity is capped at 30 KB, so the final answer's card chunk (and the live view) stay
  * well under it; longer answers overflow into follow-up messages (preview.ts owns that policy).
  */
 import { truncateCodePointPrefix } from "../text.js";
-/** The one streamed element's id — shared by create (card.ts) and update (preview.ts). */
+/** The append-only answer element's id — shared by create (card.ts) and update (preview.ts). */
 export const ANSWER_ELEMENT_ID = "answer";
+/** The volatile process element's id (thinking tail + tool lines + retry notice; live-only). */
+export const PROCESS_ELEMENT_ID = "process";
 /** Byte budget for markdown carried by ONE card (entity cap 30 KB minus JSON envelope + escaping room). */
 export const CARD_MARKDOWN_MAX_BYTES = 20 * 1024;
 /** Character budget for the settled card's summary (the chat-list / push-notification preview). */
@@ -38,7 +46,7 @@ export function cardSummary(markdown) {
         .find((l) => l !== "") ?? "";
     return truncateCodePointPrefix(line, SUMMARY_MAX_CHARS);
 }
-function cardJson(markdown, streaming, summary) {
+function cardJson(elements, streaming, summary) {
     return JSON.stringify({
         schema: "2.0",
         config: {
@@ -48,17 +56,23 @@ function cardJson(markdown, streaming, summary) {
             // "[Generating…]") is better than any fixed text we could pin.
             ...(summary ? { summary: { content: summary } } : {}),
         },
-        body: { elements: [{ tag: "markdown", content: markdown, element_id: ANSWER_ELEMENT_ID }] },
+        body: { elements },
     });
 }
-/** The live-preview card entity: streaming on, seeded with the placeholder/first view. */
-export function streamingCardJson(initial) {
-    return cardJson(initial, true);
+/** The live-preview card entity: streaming on, the process element seeded with the placeholder/queue
+ *  status and the answer element seeded EMPTY (the platform accepts an empty markdown element; it
+ *  renders zero-height until the first answer snapshot lands as a clean prefix extension of ""). */
+export function streamingCardJson(initialProcess) {
+    return cardJson([
+        { tag: "markdown", content: initialProcess, element_id: PROCESS_ELEMENT_ID },
+        { tag: "markdown", content: "", element_id: ANSWER_ELEMENT_ID },
+    ], true);
 }
-/** The settled card: final markdown, streaming off (stops the client's streaming affordance), plus
- *  the answer-derived summary so the chat list / notification shows the reply, not "[Card]". */
+/** The settled card: final markdown alone (the process block was preview-only), streaming off (stops
+ *  the client's streaming affordance), plus the answer-derived summary so the chat list / notification
+ *  shows the reply, not "[Card]". */
 export function finalCardJson(markdown) {
-    return cardJson(markdown, false, cardSummary(markdown));
+    return cardJson([{ tag: "markdown", content: markdown, element_id: ANSWER_ELEMENT_ID }], false, cardSummary(markdown));
 }
 /** The `interactive` message content that mounts a card ENTITY (vs an inline static card). */
 export function cardEntityContent(cardId) {

package/dist/channels/feishu/feishu-api.d.ts

@@ -65,15 +65,26 @@ export interface FeishuApi {
     editTextMessage(messageId: string, text: string): Promise<void>;
     /** Recall (delete) a message the bot sent. */
     deleteMessage(messageId: string): Promise<void>;
-    /** Fetch one message (the reply-referent path). Undefined when the API returns no item. */
+    /** Fetch one message (the reply-referent path). Undefined when the API returns no item.
+     *
+     *  `sender` is typed rather than `unknown` because the referent path READS it: an app-sent message
+     *  whose id is THIS app's is the agent's own, which the prompt must say instead of attributing it to
+     *  "user cli_…". `parent_id` is read by the reply-chain walk (invoke-turn): the message this one
+     *  itself replied to. The message object carries more (`root_id`, `thread_id`); they stay unnamed
+     *  until something reads them — this type is the surface in use, not a mirror of the wire. */
     getMessage(messageId: string): Promise<{
         message_id?: string;
         msg_type?: string;
+        parent_id?: string;
         body?: {
             content?: string;
         };
         mentions?: unknown[];
-        sender?: unknown;
+        sender?: {
+            id?: string;
+            id_type?: string;
+            sender_type?: string;
+        };
     } | undefined>;
     /** Download a message resource (image/file bytes). Caps at {@link MAX_DOWNLOAD_BYTES}. */
     downloadResource(messageId: string, fileKey: string, type: "image" | "file"): Promise<{

package/dist/channels/feishu/feishu.js

@@ -14,7 +14,7 @@ import { readBodyCapped } from "../body.js";
 import { text } from "../respond.js";
 import { createSeenRing } from "../seen.js";
 import { createTaskTracker } from "../tasks.js";
-import { ensureStateHome, removeRetiredStateFile } from "../state.js";
+import { ensureStateHome, loadStateFile, saveStateFile } from "../state.js";
 import { dispatchStop, isStopText } from "../stop-command.js";
 import { createTurnQueue } from "../turn-queue.js";
 import { createTurnStore } from "../turn-store.js";
@@ -58,6 +58,8 @@ function isStoredFeishuTurn(t) {
         (r.queueReplyTo === undefined || typeof r.queueReplyTo === "string") &&
         (r.replyInThread === undefined || typeof r.replyInThread === "boolean") &&
         (r.parentId === undefined || typeof r.parentId === "string") &&
+        (r.parentSession === undefined || typeof r.parentSession === "string") &&
+        (r.roomBufferKey === undefined || typeof r.roomBufferKey === "string") &&
         refs(r.images) &&
         refs(r.files) &&
         typeof r.attempts === "number");
@@ -93,16 +95,45 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         }
         const formatError = onError ?? defaultErrorMessage;
         const api = createFeishuApi({ kind, baseUrl, appId, appSecret });
-        // One bot/v3/info at startup: the bot's open_id drives the default route's group @mention summon.
-        // Until it resolves (or if it fails), group summon stays off — fail-closed — while p2p works. A
-        // mention landing in that first moment is buffered as context rather than answered; it is folded
-        // into the next answered turn in that place, so the ask is delayed, never lost.
+        // One bot/v3/info per process refreshes the bot's own open_id — the identity the default route
+        // matches group @mentions against. The CACHED copy (bot.json, seeded synchronously once the state
+        // home exists below) is what makes the first envelope safe: this fetch is fire-and-forget, and
+        // under the AgentCore posture channel construction happens INSIDE the first envelope
+        // (channels/agentcore.ts lazy construction), so a network round trip can never beat that same
+        // envelope's own dispatch — without the seed, every cold start's FIRST group mention raced this
+        // fetch and lost (field-observed: an explicit @ buffered as bystander context). The open_id is a
+        // stable property of the app, so disk beats network; the only envelope a deployment ever serves
+        // without the file is its first one, which is the deploy driver's probe — it carries no mention.
+        // No identity at all (fresh dir, no cache, fetch pending/failed) keeps today's fail-closed
+        // behavior: unmatched mentions buffer as context — delayed, never lost.
         let botOpenId;
+        let persistBotIdentity = () => { }; // bound once the state home exists
+        let invalidateBotIdentity = () => { }; // likewise
         void api.botInfo().then((me) => {
-            botOpenId = me.openId;
-            if (!botOpenId)
-                log.warn(`${label} bot/v3/info returned no open_id — group @mention summon stays off`);
-        }, (e) => log.warn(`${label} bot/v3/info failed; group @mention summon stays off until restart: ${String(e)}`));
+            if (me.openId) {
+                if (botOpenId !== undefined && botOpenId !== me.openId) {
+                    log.info(`${label} bot open_id changed (${botOpenId} → ${me.openId}) — updating the cached identity`);
+                }
+                botOpenId = me.openId;
+                persistBotIdentity(me.openId);
+            }
+            else {
+                // The call SUCCEEDED and the platform reported no identity — an affirmative "there is no
+                // bot here" (capability off, app reconfigured), not transport weather. This is the one
+                // answer that must also INVALIDATE the cache: keeping a summon identity the platform just
+                // declined to confirm would quietly turn fail-closed into fail-open.
+                log.warn(botOpenId === undefined
+                    ? `${label} bot/v3/info returned no open_id — group @mention summon stays off`
+                    : `${label} bot/v3/info returned no open_id — cached identity cleared; group @mention summon stays off`);
+                botOpenId = undefined;
+                invalidateBotIdentity();
+            }
+        }, (e) => 
+        // A FAILED call is transport weather (network, rate limit): the platform said nothing about
+        // the identity, so a cached one keeps serving — the degradation this cache exists for.
+        log.warn(botOpenId === undefined
+            ? `${label} bot/v3/info failed; group @mention summon stays off until restart: ${String(e)}`
+            : `${label} bot/v3/info failed; running on the cached identity (bot.json): ${String(e)}`));
         void api.listAppScopes().then((scopes) => {
             const grantedScope = (name) => scopes.some((scope) => scope.name === name && scope.grantStatus === 1 && (scope.type === undefined || scope.type === "tenant"));
             if (grantedScope(FEISHU_GROUP_CONTEXT_SCOPE)) {
@@ -131,10 +162,51 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
         }
         const stateHome = join(stateRoot, "channels", kind);
         ensureStateHome(stateHome); // buffers/files may carry chat content; the agent .gitignore covers .state/
-        // The participant model replaced the owned-thread index (a cache, so nothing is lost). REMOVE THIS
-        // after the release following the participant model ships — by then no live deployment can still
-        // be carrying the file. test/migration-deadline.test.ts fails when due.
-        removeRetiredStateFile(stateHome, "owned-threads.json", label);
+        // The cached bot identity (rationale at the botInfo block above): seed synchronously — the
+        // factory runs to completion before any promise resolves, so botOpenId is still unset here and
+        // the seed is what the first envelope's dispatch sees. Refresh keeps the file current.
+        //
+        // BOUND TO THE APP: the state home is per channel KIND, and an operator can point kept state at
+        // a different app (a recreated app, a tenant migration). A cached identity from another app
+        // would make THIS bot treat mentions of the OLD bot as its own summons — identity impersonation,
+        // strictly worse than the race the cache removes — so the cache counts only when it names the
+        // current appId. A mismatch is not noise worth warning about: the next persist IS the migration.
+        const botFile = join(stateHome, "bot.json");
+        const storedBot = loadStateFile(botFile);
+        let cachedOpenId;
+        if (storedBot !== undefined) {
+            if (typeof storedBot.appId !== "string") {
+                log.warn(`${label} unexpected shape in ${botFile} — ignoring the cached bot identity`);
+            }
+            else if (storedBot.appId === appId && typeof storedBot.openId === "string") {
+                cachedOpenId = storedBot.openId;
+            }
+        }
+        botOpenId ??= cachedOpenId;
+        persistBotIdentity = (openId) => {
+            if (openId === cachedOpenId)
+                return;
+            cachedOpenId = openId;
+            try {
+                saveStateFile(botFile, { appId, openId });
+            }
+            catch (e) {
+                log.warn(`${label} could not persist the bot identity to ${botFile} — the next cold start races bot/v3/info again: ${String(e)}`);
+            }
+        };
+        invalidateBotIdentity = () => {
+            if (cachedOpenId === undefined)
+                return;
+            cachedOpenId = undefined;
+            try {
+                // `{ appId }` with no openId reads as "no cache" at the loader — the atomic write is reused
+                // instead of introducing a deletion path.
+                saveStateFile(botFile, { appId });
+            }
+            catch (e) {
+                log.warn(`${label} could not clear the cached bot identity ${botFile}: ${String(e)}`);
+            }
+        };
         const threadParticipants = createThreadParticipants(join(stateHome, "thread-participants.json"), label);
         /** This channel's place key for a thread (the shared store is key-agnostic). */
         // The SAME identity the session uses (`placeKey`) — a thread's place. Defining it twice would let a
@@ -235,13 +307,31 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 // this snapshot before either commits it. That fan-out loses nothing; claiming by buffer key
                 // would instead couple otherwise-independent root sessions and require failure rollback.
                 const { text: recent, consumed } = buffer.peek(rec.bufferKey);
-                const prompt = recent ? `[recent group discussion:\n${recent}\n]\n\n${rec.baseText}` : rec.baseText;
-                const buffered = collectFeishuBufferedAttachments(consumed, {
+                // PEEK and never commit: the room still owes this discussion to its OWN memory (§8).
+                const room = rec.roomBufferKey !== undefined ? buffer.peek(rec.roomBufferKey) : undefined;
+                const roomBlock = room?.text
+                    ? `[recent discussion in the room this thread branched from — not yet answered there:\n${room.text}\n]\n\n`
+                    : "";
+                const threadBlock = recent ? `[recent group discussion:\n${recent}\n]\n\n` : "";
+                const prompt = `${roomBlock}${threadBlock}${rec.baseText}`;
+                // Room entries FIRST: the collector keeps the TAIL under its cap, so the thread's own
+                // attachments win the slots.
+                const buffered = collectFeishuBufferedAttachments([...(room?.consumed ?? []), ...consumed], {
                     images: rec.images.map((ref) => ({ messageId: ref.msg, key: ref.key })),
                     files: rec.files.map((ref) => ({ messageId: ref.msg, key: ref.key, name: ref.name })),
                 });
+                // Recorded at ingress (see submit) — never re-derived from the session key, which may be a
+                // routed OPAQUE id that only looks like a place key.
+                const parentSession = rec.parentSession;
                 try {
-                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, { api, chatId: rec.chatId, filesDir: join(stateHome, "files"), label }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
+                    await streamFeishuReply(invokeFeishuTurn(agent, rec.session, prompt, {
+                        api,
+                        chatId: rec.chatId,
+                        filesDir: join(stateHome, "files"),
+                        label,
+                        appId,
+                        ...(parentSession !== undefined ? { parentSession } : {}),
+                    }, { primary: { images: rec.images, files: rec.files, parentId: rec.parentId }, buffered }, () => {
                         // Drop intent first: a crash between these writes may re-fold answered context later,
                         // but can never replay this turn after its context was removed.
                         store.remove(rec.id);
@@ -391,7 +481,19 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
             // Memory follows the place (participant model §5): one session per chat, and one per thread.
             // Keyed by `thread_id`, never `root_id` — the platform's root_id tracks the reply chain and can
             // differ between messages of ONE thread, which would split a side conversation in two.
-            const session = r.session ?? placeKey(kind, m);
+            const routed = r.session;
+            const session = routed ?? placeKey(kind, m);
+            // Lineage is recorded ONLY for the default place-derived session. A routed session id is
+            // OPAQUE (the route contract), and re-parsing it as a place key would let a three-segment id
+            // like "tenant:user:alice" masquerade as a thread and inherit from "tenant:user" — a
+            // cross-session injection. Derived from the MESSAGE (the fact this channel owns), at record
+            // time, where routed-ness is still known; the dequeue path only reads it back.
+            const parentSession = routed === undefined && m.thread_id !== undefined ? placeKey(kind, { chat_id: m.chat_id }) : undefined;
+            // Read BEFORE this turn records its own participation below, or it is always true. Keyed by the
+            // SOURCE chat, never the answer target a route may name (§8).
+            const roomBufferKey = parentSession !== undefined && !threadParticipants.agentSpokeIn(session)
+                ? feishuBufferPlaceKey({ chatId: m.chat_id })
+                : undefined;
             const chatId = r.chatId ?? m.chat_id;
             const sameTarget = chatId === m.chat_id;
             // Answer where asked (§4): quote in a group so the ask is identifiable among many speakers,
@@ -443,6 +545,8 @@ function createFeishuRuntimeFactory(profile, opts, factoryName) {
                 // already have; it also pins WHICH message is being answered, which a long thread benefits
                 // from anyway.
                 parentId: m.parent_id,
+                ...(parentSession !== undefined ? { parentSession } : {}),
+                ...(roomBufferKey !== undefined ? { roomBufferKey } : {}),
                 images,
                 files,
             }, true);

package/dist/channels/feishu/invoke-turn.d.ts

@@ -8,8 +8,9 @@
  *
  * Inputs have two tiers. PRIMARY is the summoning message plus the message it explicitly replied to;
  * any load failure there aborts visibly so the Agent never runs without an input the user pointed at.
- * BUFFERED resources come from earlier un-summoned thread/group discussion and degrade per attachment:
- * one expired background file must not block the current ask or hide its still-readable siblings.
+ * BUFFERED resources come from earlier un-summoned thread/group discussion and from reply-chain
+ * ancestors, and degrade per attachment: one expired background file must not block the current ask
+ * or hide its still-readable siblings.
  */
 import type { Agent, AgentEvent } from "../../agent.ts";
 import { type BusyRetry } from "../invoke-turn-kit.ts";
@@ -21,6 +22,15 @@ export interface FeishuTurnTransport {
     chatId: string;
     filesDir: string;
     label: string;
+    /** THIS app's own id (`cli_…`) — the identity a fetched message's `sender.id` carries when the
+     *  sender is an app. Needed to tell the agent's OWN messages from any other bot's in the same chat:
+     *  `sender_type` alone says "some app", which is not the question the referent path asks. */
+    appId: string;
+    /** The place this thread branched from (the chat's main place), when the turn runs in a thread —
+     *  rides the Scope's lineage extension so a NEW thread session starts from what the room knew
+     *  (participant-model.md §5). The engine reads it once, at session creation; every later turn
+     *  carries it inertly. */
+    parentSession?: string;
 }
 /** An attachment reference: the resource key inside its CARRYING message (the resource API addresses
  *  bytes by message_id + key, so the pair travels together through the turn record). */