feat(chat): deliver proactive task messages to agent chats (#18374)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agent Chat gives each person a persistent conversation with each
agent.
> - Tasks and routines produce results outside that conversation.
> - Those runs need a safe way to bring a requested result back to the
person.
> - The server must select the agent's own chat and check the source
task's access rules.
> - This pull request adds proactive chat messages and unread
indicators.
> - People can see the result, open its source task, and reply in the
same chat.

## Linked Issues or Issue Description

**Subsystem affected**

Server, native runner tools, shared contracts, database, and UI.

**Problem or motivation**

An agent can report progress on a task or comment on an authorized task.
It cannot send a routine result to its own standing chat with the
responsible person. A morning review routine therefore cannot leave a
visible digest in that person's chat.

**Proposed solution**

Add `send_chat_message({body, idempotencyKey})` and `POST
/api/agents/me/chat/messages`. The server selects the company, agent,
and responsible person from the active run. It saves an attributed
comment and audit record in one transaction. The chat shows a
source-task link and per-person unread state.

**Alternatives considered**

A destination parameter on a generic comment tool would expose
unnecessary routing authority. A new delivery worker would add another
durable delivery path. This change uses a dedicated tool and the
existing comment and live-event paths.

**Roadmap alignment**

This extends the experimental Agent Chat capability in `ROADMAP.md`. The
existing `enableAgentChat` setting controls it. Related public work:
Refs #13282, Refs #13283, and Refs #14408. Searches for proactive chat
and unread chat found no duplicate PR.

## What Changed

- Add a focused messaging service shared by the native tool and HTTP
route. It checks current run ownership, execution mode, recipient
membership, task access, and task privacy.
- Reuse the canonical company/agent/person conversation. Save the
comment and audit record together. Keep task completion and chat
execution separate from delivery.
- Add source-task provenance and source-scoped retry keys. Identical
retries return the saved receipt. Changed content returns a conflict.
- Enforce the conversation's fixed agent at the shared comment-write
boundary. Keep normal reply cancellation and session checks.
- Add chat unread state, accessible agent dots, aggregate Chat
indicators, and visible-message read cutoffs. Refresh through existing
live events.
- Add the request-key constraint, native tool contracts, documentation,
capability maps, stories, and regression coverage.

## Verification

- Local delivery/security proof: all 38 proactive-message cases pass.
Eight credential-scope regressions and four quota regressions fail
against the prior source. The repaired delivery and canonical
cross-issue cap suites pass all 49 cases; all 31 OpenAPI tests, server
typecheck, and capability-map checks pass. The shared per-run cap covers
native and HTTP sends, mixed ordinary mutations, concurrent last-slot
contention, and retry/recovery without double charging.
- Credential tests preserve the authenticated person and authorizer;
reject bridge/test credentials and persisted skill-test runs after
task-mode changes; and recheck API-key revocation, scope, and
responsible person after destination locking. The earlier
delivery/native-authority suites passed all 74 cases before the four
quota additions.
- Four PostgreSQL contention cases cover native and HTTP sends plus
retries during a native chat mutation. All four deadlock against the
earlier source and pass with destination-before-source/run locking.
Recovery and human-reply delivery enqueue only the human comment; a
proactive digest never wakes the chat agent.
- Passed 108 companion conversation, native-authority, and OpenAPI
tests; 112 runner catalog/workflow-report tests; 47 completion-delivery
tests; and 25 project-handoff tests. Focused runner tests cover native
tool availability without generic API tools.
- All 327 affected UI tests, UI typecheck, token gates, and catalog
checks pass. The read hook retries at most three times, respects server
retry delay, coalesces only seen cutoffs, recovers on reconnect, and
cancels on scope changes.
- Real browser journeys with a deterministic process agent verify
routine-to-chat delivery, first-chat creation, unread state across
reload, the source link, secondary chat navigation, and a follow-up
reply referring to the digest. This does not qualify live GitHub
retrieval or model output quality.
- The Storybook showcase uses production components with deterministic
network fixtures. Rendered interactions pass for the landing, ordinary
read success, transient read recovery, and persistent failure after
bounded retries. Both Chat navigation variants update from two unread
chats to one while only Kodi's dot clears. Mobile and light variants
were reviewed. The existing Coordinator Recents label contrast finding
is unchanged; no Linux visual baseline archive exists.
- Current master's independent sandbox migration retains 0418.
Regenerated the feature migration as 0419 from the combined schema and
retained exactly the newest five snapshots; numbering/safety, replay,
and schema-drift checks pass.
- Workspace typecheck and build passed before PR preparation; canonical
server/UI typechecks passed again on the combined tree. Migration
`0419_slippery_impossible_man.sql` passes safety and schema drift checks
on disposable PostgreSQL, including interrupted index repair, concurrent
migrators, one-time owner read-state backfill, preserved receipts, and
two SQL replays. A default five-second local snapshot comparison timed
out; a diagnostic 30-second run passed without drift.
- Earlier failures are retained in the record: full local `pnpm
test:run` and broad shards encountered embedded-PostgreSQL startup,
timing, and provider-recovery failures. Thirteen selected
external-channel cases pass in isolation on the original and changed
sources; an unordered comment-row assertion now explicitly orders both
reads. The earlier route registry, native tool count, runner catalog,
and accessible Chat badge-name failures were fixed and passed full
remote CI on `920b3bb7db`.
- Repeated managed-skill server8 failures came from CI's newer synthetic
merge: its Cloud guard correctly rejected the old local-disk fixture.
Master independently repaired the fixture in #18385; this branch keeps
that repair unchanged. All 57 managed-skill and Cloud prerequisite cases
pass on the combined tree, and that fixture has no remaining PR diff.
- Current reviewed head `dc16f314739a6d977bed21cb1446d0e80a541578`:
Greptile 5/5 with no findings, Superagent security assessment passed,
advisory Paperclip Review 5/5 with no findings, and zero open review
threads. All 55 current-head check runs pass, with five expected skips
and the advisory review neutral at 5/5; Snyk also passes. No checks are
pending or failing. Protected squash auto-merge is enabled and is
waiting for required code-owner approval. A normal exact-head merge was
refused by the base-branch policy; no admin bypass was used. The
previous head's Superagent quota finding is fixed and covered above.

## Risks

- Chat remains company-visible. Delivery rejects a source task with
private-task, project, or ancestor restrictions.
- Read state uses a comment timestamp cutoff. The server retains
database precision and never moves a read receipt backward.
- The new unique constraint changes comment query planning. An existing
regression now uses an explicit row order. The migration builds the
unique index concurrently, then takes a brief table lock to attach it.
It uses the existing top-level migration and interrupted-index recovery
path.
- The upgrade backfills missing chat-owner read-state rows at the latest
existing agent comment. Existing read receipts remain intact. New chats
can still be unread before the human participates.
- Quota observation commits atomically with delivery. A rejected send
rolls back its attempted denial audit row and any first-chat creation;
the canonical warning remains in server logs, and previously spent quota
remains enforced. Identical/conflicting retries and receipt recovery
spend no extra slot.
- This version delivers in-app only. It adds no external-channel, push,
or email delivery.
- Local full-suite acceptance remains limited by the failures recorded
above. The feature stays behind `enableAgentChat`.

## Model Used

OpenAI Codex. PR preparation and CI work used `gpt-6.1-sol` with tool
use and code execution. The earlier implementation also used Codex, but
its exact model ID was not recorded in the visible session. The
context-window size was not provided.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run focused tests locally and they pass; the broad local
failures are recorded above
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

doc/DATABASE.md

@@ -1,5 +1,20 @@
 # Database
 
+### Proactive agent chat messages
+
+Migration `0419_slippery_impossible_man.sql` adds an agent-scoped unique constraint
+on `issue_comments(issue_id, author_agent_id, client_request_id)` alongside the
+existing human request constraint. Proactive delivery stores a source-task-scoped
+retry key and server-authored `metadata.chatMessage` provenance/content fingerprint.
+The comment and audit record commit together; a retry returns the original receipt.
+Conversation creation reuses the unique company/agent/human identity and existing
+advisory-lock order. No message outbox is added.
+
+Chat list/detail unread projections reuse `issue_read_states`, including chats
+with no human participation. Read cutoffs use the exact PostgreSQL comment
+timestamp; upserts take the greatest previous/new cutoff so delayed requests
+cannot move a read receipt backward or clear a later unseen arrival.
+
 Paperclip uses PostgreSQL via [Drizzle ORM](https://orm.drizzle.team/). There are three ways to run the database, from simplest to most production-ready.
 
 ### Persistent case handoffs

doc/PRODUCT.md

@@ -358,6 +358,14 @@ See [iMessage Photon](connections/IMESSAGE-PHOTON.md) for the implementation
 contract, setup, recovery, boundaries, and qualification status.
 ### Experimental persistent agent conversations
 
+Agents can deliver proactive task and routine results into their own chat with
+the task's responsible human. A morning PR digest arrives as an agent message
+with a source-task link and unread indicators, even before the first human
+message. The person can reply using the digest as context. Publishing a message
+and completing work are separate actions; sending never starts or interrupts a
+chat turn. Delivery obeys membership, run authority and task privacy, and stays
+behind the Agent Chat setting. This version delivers in-app only.
+
 Agent Chat is an opt-in core task presentation (`enableAgentChat`, off by default). Each person has one persistent task-backed conversation per agent and company, with ordinary company task visibility. The shared task composer, transcript, tools, files, and document panel remain the interaction surface. Agents clarify goals and hand substantial execution to linked, assigned tasks; a reply ends a turn without completing the conversation. `/new` starts fresh provider context in the same conversation while preserving visible history and artifacts. Healthy idle conversations wait for a message and do not count as unfinished execution work. See `doc/plans/2026-09-10-agent-chat.md` for the implementation contract.
 
 ### Agent chat project handoff (2026-09-11)

doc/SPEC-implementation.md

@@ -2117,6 +2117,40 @@ placements may use a lazy live character. See [agent-personas.md](agent-personas
 for persistence, migration, rendering, and integration contracts.
 ### Experimental task-backed agent chat (2026-09-10)
 
+Ordinary task and routine runs in standard mode may publish with
+`send_chat_message({body,idempotencyKey})` or `POST /api/agents/me/chat/messages`.
+The authenticated company, agent and run responsible human determine the sole
+destination. Recheck execution ownership, membership, task/destination access
+and canonical source privacy at commit. Reject missing recipients, restricted
+source tasks, Ask/planning/review/watchdog runs and stopped runs. The shared
+comment-write boundary enforces the fixed conversation agent.
+Skill-test and task-bridge credentials cannot publish into standing chats.
+Persisted skill-test run boundaries remain in force after a task-mode change.
+Preserve the credential and external-user access intersection and recheck key
+revocation, scope and responsible-person identity before commit.
+Each new delivery charges the shared per-run cross-issue influence cap in the
+same transaction. Retries, conflicting content and receipt-only recovery do not
+spend another slot. Cap exhaustion returns the canonical 429 response and leaves
+no message or newly created conversation behind.
+
+The chat messaging service atomically creates a waiting conversation if needed
+and commits an attributed issue comment and audit record. Agent request IDs are
+unique per conversation and author; keys incorporate the source task for retries
+across runs, and changed content conflicts. Server-authored provenance identifies
+the source task and run. Existing events refresh discovery, messages and unread
+projections. Source execution transcripts remain outside the chat's linked-run
+history. There is no delivery worker, message outbox or extra model turn.
+
+Sending does not change task disposition, cancel/settle a chat turn or suppress
+automatic handoff completion notifications. `/new` permits future background
+messages in the current history. Ordinary chat replies retain session checks.
+Chat list/detail responses use per-user read state before human participation;
+the foreground chat marks rendered messages read through an optional comment
+cutoff, retaining unseen concurrent arrivals. Existing navigation ordering is
+preserved with accessible unread dots and an aggregate Chat indicator.
+`enableAgentChat` gates delivery; external channels, push/email and private-chat
+redesign are outside this contract.
+
 `enableAgentChat` is an instance experimental flag, default false. Conversation containers remain issues, unique by `(company_id, conversation_agent_id, conversation_user_id)`. The authenticated board actor supplies ownership; local trusted mode uses `local-board`. Ordinary company task access applies. A conversation's agent assignment and identity are immutable through ordinary updates; terminal status mutations are rejected.
 
 `GET /api/companies/:companyId/chats/:agentRef` reads an existing conversation or null. `POST` atomically resolves its issue when adding a chat or on first send/upload. `GET /api/companies/:companyId/chats` lists only the current board user’s conversations in that company, subject to ordinary issue read access. The Chat navigation opens a searchable secondary sidebar with agent avatars and a picker for starting or reopening the same per-agent conversation. Existing issue comment, attachment, document, interaction, and run APIs apply thereafter. User chat comments require an idempotent UUID `clientRequestId`. Conversation delivery preserves comment order through the existing issue execution queue; the durable comment outbox repairs the commit-to-enqueue crash window.

doc/SPEC.md

@@ -2,6 +2,15 @@
 
 Target specification for the Paperclip control plane. Living document — updated incrementally during spec interviews.
 
+Proactive in-app updates let an active standard task or routine publish to its
+agent's persistent conversation with the run's responsible human. The server
+derives the destination, enforces current authority and company-visible chat
+privacy, and persists an attributed, idempotent comment with source-task provenance.
+Unread state belongs to the viewing human. Sending is independent of task
+completion and chat execution; future messages remain possible after `/new`.
+The V1 contract is specified under experimental task-backed agent chat in
+`doc/SPEC-implementation.md`.
+
 Experimental standalone cases provide persistent structured work records that can
 exist independently of execution. Prompt-driven handoffs move their primary
 ordinary task between agents while retaining case data and history. Existing task

docs/guides/agent-developer/comments-and-communication.md

@@ -5,6 +5,36 @@ summary: How agents communicate via issues
 
 Comments on issues are the primary communication channel between agents. Every status update, question, finding, and handoff happens through comments.
 
+## Proactive messages to the human's chat
+
+Use `report_progress` for the current task, `comment_on_task` for an authorized
+task, and `send_chat_message` for your own persistent chat with the current run's
+responsible human:
+
+```json
+send_chat_message({ "body": "These three PRs need review…", "idempotencyKey": "morning-pr-digest-2026-10-30" })
+```
+
+HTTP agents use `POST /api/agents/me/chat/messages` with the same JSON body and
+authenticated task-run credentials. There are no destination parameters. The
+server resolves company, agent and responsible human, atomically creating a
+waiting conversation when needed. Missing or revoked recipients fail explicitly.
+The response includes `commentId`, `conversationId`, `chatUrl`, `sourceTaskId`
+and `replayed`. Retry with the same key and body, including across runs of the
+same source task. Changed content with a used key conflicts.
+
+Delivery requires Agent Chat enabled and an authorized active standard task run.
+Ask, planning, review and watchdog runs cannot send. Private tasks, private
+projects and restricted ancestors cannot publish into company-visible chats.
+Ordinary comment endpoints enforce the chat's fixed agent and current session.
+
+The message appears as the agent with a source-task link and marks the chat
+unread. Sending never starts a chat run, interrupts a reply, settles a pending
+turn or completes the source task. Complete your task separately. Automatic
+handoff completion notifications still apply. `/new` resets context but permits
+future proactive messages; subsequent replies can use messages delivered after
+the reset. This API delivers in-app messages only.
+
 ## Posting Comments
 
 ```

maps/agent-access-map/agent-chat.md

@@ -40,6 +40,30 @@ missing from the generated API catalog.
 
 ## `history`
 
+Proactive publication: native `send_chat_message` and
+`POST /api/agents/me/chat/messages` accept only Markdown body and idempotency key.
+The server derives company, sender and responsible human from the authenticated
+run and atomically resolves the same per-agent/human conversation. This operation
+is available independently of generic API tools, only to active standard task
+runs with standard credentials. Skill-test and task-bridge credentials, persisted
+skill-test runs, Ask/planning/review/watchdog, stale/stopped runs, revoked recipients and
+restricted source tasks are denied. The shared comment boundary rejects other
+agents and execution-task writes that bypass this path. Comment/audit persistence
+retains real agent/run attribution and server-owned source provenance.
+Credential scope, responsible human and external authorizer remain part of access
+checks. API keys are rechecked under a row lock before the delivery commits.
+New deliveries spend the existing shared per-run cross-issue influence budget;
+receipt retries and recovery spend no extra slot. Exhaustion returns the standard 429
+denial and rolls back the attempted delivery, including first-chat creation.
+
+`GET /api/companies/{companyId}/chats` and its detail endpoint include the current
+human's unread state. `POST /api/issues/{id}/read` accepts an optional
+`throughCommentId` for the owning human's conversation. Concurrent unseen arrivals
+remain unread. Source: [delivery owner](../../server/src/services/agent-chat-messages.ts),
+[database tests](../../server/src/__tests__/agent-chat-messages.test.ts), and
+[browser journey](../../tests/e2e/agent-chat-messages.spec.ts). Test definitions
+are not evidence that a live provider or whole capability has been qualified.
+
 Capability ID: `agent-chat/history`.
 
 Review: `baseline`.

maps/feature-map/agent-chat.md

@@ -23,6 +23,12 @@ Agent access: [companion](../agent-access-map/agent-chat.md).
 
 ### `agent-conversation`
 
+Task and routine results can arrive proactively in the agent's standing chat.
+Each message has a source-task link; the agent row and Chat navigation indicate
+unread messages, including first delivery before any human chat. Foreground
+messages at the bottom of the chat are marked read with a comment cutoff.
+The existing ordering and per-human/company isolation remain in effect.
+
 Open `/chats`, choose an agent, or use `/chats/:agentRef` and its conversation sidebar.
 
 With Coordinator enabled, the composer exposes the shared model/thinking-level picker for supported agents. The agent stays fixed in this control; switching agents remains in the chat header. Choices save as conversation overrides on send, preserving the agent's configuration. A first message creates the conversation before saving settings and submitting through the ordered comments endpoint.
@@ -49,6 +55,14 @@ Local browser recipe: [long-chat startup and scrolling](../../tests/perf/agent-c
 
 Automated: [chat landing](../../ui/src/pages/AgentChats.test.tsx) checks recent-chat routing; [conversation service](../../server/src/__tests__/agent-conversations.test.ts) covers persisted conversation behavior.
 
+Automated: [proactive delivery](../../server/src/__tests__/agent-chat-messages.test.ts)
+exercises native/HTTP delivery, concurrency, retries, authority, privacy, active
+turns, resets and unread cutoffs. [Read visibility](../../ui/src/hooks/useAgentChatRead.test.tsx)
+checks foreground/bottom gating and unseen arrivals. The [routine digest journey](../../tests/e2e/agent-chat-messages.spec.ts)
+uses real app APIs and a deterministic process agent to verify first-chat discovery,
+unread state across reloads, source navigation and follow-up context. It does not
+qualify live PR retrieval or a model's editorial choices.
+
 Automated: [composer picker](../../ui/src/components/task-chat/ComposerRunSettingsPicker.test.tsx) covers fixed-agent model/effort selection on desktop and mobile; [composer](../../ui/src/components/task-chat/TaskChatComposer.test.tsx) covers Coordinator gating and settings submission without reassignment. [Task detail](../../ui/src/pages/IssueDetail.test.tsx) verifies canonical first/existing-chat IDs, settings-before-comment ordering, and no comment submission when settings fail to save. These tests mock the API and do not prove provider execution with the chosen model.
 
 Automated: [conversation delivery](../../server/src/__tests__/agent-conversation-delivery.test.ts)

packages/db/src/agent-chat-messages-migration.test.ts

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import postgres from "postgres";
+import { describe, expect, it } from "vitest";
+import { applyPendingMigrations } from "./client.js";
+import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./test-embedded-postgres.js";
+
+const support = await getEmbeddedPostgresTestSupport();
+const indexName = "issue_comments_agent_client_request_uq";
+const migrationFile = "0419_slippery_impossible_man.sql";
+
+(support.supported ? describe : describe.skip)("agent chat message migration", () => {
+  it("repairs an interrupted index build and backfills old chat owners only once", async () => {
+    const database = await startEmbeddedPostgresTestDatabase("agent-chat-message-migration-");
+    const sql = postgres(database.connectionString, { max: 1, onnotice: () => {} });
+    try {
+      const content = await readFile(new URL(`./migrations/${migrationFile}`, import.meta.url), "utf8");
+      const hash = createHash("sha256").update(content).digest("hex");
+      await sql`DELETE FROM drizzle.__drizzle_migrations WHERE hash=${hash}`;
+      await sql.unsafe(`ALTER TABLE issue_comments DROP CONSTRAINT ${indexName}`);
+      const companies = await sql`INSERT INTO companies (name,issue_prefix) VALUES ('Chat migration','CMI1'),('Other company','CMI2') RETURNING id`;
+      const companyId = companies[0]!.id;
+      const [agent] = await sql`INSERT INTO agents (company_id,name,adapter_type) VALUES (${companyId},'Kodi','process') RETURNING id`;
+      const chats = await sql`INSERT INTO issues (company_id,title,conversation_agent_id,conversation_user_id,conversation_state,assignee_agent_id)
+        VALUES (${companyId},'Missing read state',${agent!.id},'legacy-owner','waiting',${agent!.id}),
+          (${companyId},'Existing read state',${agent!.id},'existing-owner','waiting',${agent!.id}) RETURNING id,conversation_user_id`;
+      for (const chat of chats) {
+        await sql`INSERT INTO issue_comments (company_id,issue_id,author_agent_id,body,created_at)
+          VALUES (${companyId},${chat.id},${agent!.id},'Existing message','2026-01-02T00:00:00Z')`;
+      }
+      await sql`INSERT INTO issue_read_states (company_id,issue_id,user_id,last_read_at)
+        VALUES (${companyId},${chats[1]!.id},'existing-owner','2026-01-01T00:00:00Z')`;
+      await expect(sql.unsafe(`CREATE UNIQUE INDEX CONCURRENTLY ${indexName} ON companies ((true))`)).rejects.toThrow();
+      await Promise.all([applyPendingMigrations(database.connectionString), applyPendingMigrations(database.connectionString)]);
+      const [index] = await sql`SELECT indisvalid,indisunique FROM pg_index WHERE indexrelid=${indexName}::regclass`;
+      expect(index).toEqual({ indisvalid: true, indisunique: true });
+      const [constraint] = await sql`SELECT count(*)::int count FROM pg_constraint WHERE conname=${indexName} AND conrelid='issue_comments'::regclass`;
+      expect(constraint!.count).toBe(1);
+      const readStates = await sql`SELECT user_id,last_read_at FROM issue_read_states WHERE company_id=${companyId} ORDER BY user_id`;
+      expect(readStates.map(row => [row.user_id, row.last_read_at.toISOString()])).toEqual([
+        ["existing-owner", "2026-01-01T00:00:00.000Z"],
+        ["legacy-owner", "2026-01-02T00:00:00.000Z"],
+      ]);
+      const [newChat] = await sql`INSERT INTO issues (company_id,title,conversation_agent_id,conversation_user_id,conversation_state,assignee_agent_id)
+        VALUES (${companyId},'New unread chat',${agent!.id},'new-owner','waiting',${agent!.id}) RETURNING id`;
+      await sql`INSERT INTO issue_comments (company_id,issue_id,author_agent_id,body)
+        VALUES (${companyId},${newChat!.id},${agent!.id},'New digest')`;
+      for (let replay = 0; replay < 2; replay++) {
+        for (const statement of content.split("--> statement-breakpoint").filter(statement => statement.trim())) {
+          await sql.unsafe(statement);
+        }
+      }
+      expect(await sql`SELECT id FROM issue_read_states WHERE issue_id=${newChat!.id}`).toEqual([]);
+      const afterReplay = await sql`SELECT user_id,last_read_at FROM issue_read_states WHERE company_id=${companyId} ORDER BY user_id`;
+      expect(afterReplay).toEqual(readStates);
+      const [history] = await sql`SELECT count(*)::int count FROM drizzle.__drizzle_migrations WHERE hash=${hash}`;
+      expect(history!.count).toBe(1);
+    } finally {
+      await sql.end();
+      await database.cleanup();
+    }
+  }, 120_000);
+});

packages/db/src/client.ts

@@ -564,6 +564,7 @@ const MIGRATIONS_WITH_TOP_LEVEL_STATEMENTS = new Set([
   "0412_tearful_squadron_supreme.sql",
   "0413_tired_kronos.sql",
   "0414_closed_edwin_jarvis.sql",
+  "0419_slippery_impossible_man.sql",
 
 
   "0384_funny_adam_warlock.sql",

packages/db/src/migrations/0419_slippery_impossible_man.sql

@@ -0,0 +1,24 @@
+CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS "issue_comments_agent_client_request_uq"
+  ON "issue_comments" ("issue_id", "author_agent_id", "client_request_id");
+--> statement-breakpoint
+DO $$ BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+    WHERE conname = 'issue_comments_agent_client_request_uq'
+      AND conrelid = 'issue_comments'::regclass
+  ) THEN
+    INSERT INTO "issue_read_states" ("company_id", "issue_id", "user_id", "last_read_at")
+    SELECT i."company_id", i."id", i."conversation_user_id", max(c."created_at")
+    FROM "issues" i
+    JOIN "issue_comments" c ON c."company_id" = i."company_id" AND c."issue_id" = i."id"
+    WHERE i."conversation_agent_id" IS NOT NULL AND i."conversation_user_id" IS NOT NULL
+      AND c."deleted_at" IS NULL AND c."author_agent_id" IS NOT NULL
+      AND c."author_type" IS DISTINCT FROM 'system'
+      AND c."presentation" ->> 'kind' IS DISTINCT FROM 'system_notice'
+      AND c."origin" = 'comment'
+    GROUP BY i."company_id", i."id", i."conversation_user_id"
+    ON CONFLICT ("company_id", "issue_id", "user_id") DO NOTHING;
+    ALTER TABLE "issue_comments" ADD CONSTRAINT "issue_comments_agent_client_request_uq"
+      UNIQUE USING INDEX "issue_comments_agent_client_request_uq";
+  END IF;
+END $$;

packages/db/src/migrations/meta/0419_snapshot.json

@@ -1,6 +1,6 @@
 {
-  "id": "27c9008c-60e3-449b-9630-9e4977fad444",
-  "prevId": "5690a14a-f9cc-41a6-af51-c27f688f4ef6",
+  "id": "52cf22f3-3bd9-4b0f-8d23-b422bb0d2540",
+  "prevId": "c777fa84-85a6-418f-bea1-0d60b56cf071",
   "version": "7",
   "dialect": "postgresql",
   "tables": {
@@ -19052,6 +19052,98 @@
       "checkConstraints": {},
       "isRLSEnabled": false
     },
+    "public.company_skill_mutation_receipts": {
+      "name": "company_skill_mutation_receipts",
+      "schema": "",
+      "columns": {
+        "company_id": {
+          "name": "company_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "fingerprint": {
+          "name": "fingerprint",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "skill_id": {
+          "name": "skill_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "version_id": {
+          "name": "version_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "response": {
+          "name": "response",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "company_skill_mutation_receipts_key_idx": {
+          "name": "company_skill_mutation_receipts_key_idx",
+          "columns": [
+            {
+              "expression": "company_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "company_skill_mutation_receipts_company_id_companies_id_fk": {
+          "name": "company_skill_mutation_receipts_company_id_companies_id_fk",
+          "tableFrom": "company_skill_mutation_receipts",
+          "tableTo": "companies",
+          "columnsFrom": [
+            "company_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
     "public.company_skill_repository_snapshots": {
       "name": "company_skill_repository_snapshots",
       "schema": "",
@@ -19079,7 +19171,46 @@
           "name": "file_inventory",
           "type": "jsonb",
           "primaryKey": false,
-          "notNull": true
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "storage": {
+          "name": "storage",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "upload": {
+          "name": "upload",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "restore": {
+          "name": "restore",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "migration_at": {
+          "name": "migration_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false,
+          "default": "now()"
+        },
+        "maintenance_at": {
+          "name": "maintenance_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false,
+          "default": "now()"
+        },
+        "restore_retry_at": {
+          "name": "restore_retry_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
         },
         "created_at": {
           "name": "created_at",
@@ -19110,6 +19241,38 @@
           "concurrently": false,
           "method": "btree",
           "with": {}
+        },
+        "company_skill_snapshots_migration_idx": {
+          "name": "company_skill_snapshots_migration_idx",
+          "columns": [
+            {
+              "expression": "migration_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"company_skill_repository_snapshots\".\"migration_at\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "company_skill_snapshots_maintenance_idx": {
+          "name": "company_skill_snapshots_maintenance_idx",
+          "columns": [
+            {
+              "expression": "maintenance_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"company_skill_repository_snapshots\".\"maintenance_at\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
         }
       },
       "foreignKeys": {
@@ -19999,6 +20162,25 @@
           "primaryKey": false,
           "notNull": false
         },
+        "package_snapshot_id": {
+          "name": "package_snapshot_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "package_file_map": {
+          "name": "package_file_map",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "migration_at": {
+          "name": "migration_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false,
+          "default": "now()"
+        },
         "revision_number": {
           "name": "revision_number",
           "type": "integer",
@@ -20057,6 +20239,52 @@
         }
       },
       "indexes": {
+        "company_skill_versions_migration_idx": {
+          "name": "company_skill_versions_migration_idx",
+          "columns": [
+            {
+              "expression": "migration_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"company_skill_versions\".\"migration_at\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "company_skill_versions_package_snapshot_idx": {
+          "name": "company_skill_versions_package_snapshot_idx",
+          "columns": [
+            {
+              "expression": "package_snapshot_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "company_skill_versions_repository_snapshot_idx": {
+          "name": "company_skill_versions_repository_snapshot_idx",
+          "columns": [
+            {
+              "expression": "repository_snapshot_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
         "company_skill_versions_skill_revision_idx": {
           "name": "company_skill_versions_skill_revision_idx",
           "columns": [
@@ -20168,6 +20396,19 @@
           "onDelete": "restrict",
           "onUpdate": "no action"
         },
+        "company_skill_versions_package_snapshot_id_company_skill_repository_snapshots_id_fk": {
+          "name": "company_skill_versions_package_snapshot_id_company_skill_repository_snapshots_id_fk",
+          "tableFrom": "company_skill_versions",
+          "tableTo": "company_skill_repository_snapshots",
+          "columnsFrom": [
+            "package_snapshot_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "restrict",
+          "onUpdate": "no action"
+        },
         "company_skill_versions_author_agent_id_agents_id_fk": {
           "name": "company_skill_versions_author_agent_id_agents_id_fk",
           "tableFrom": "company_skill_versions",
@@ -20613,6 +20854,78 @@
       "checkConstraints": {},
       "isRLSEnabled": false
     },
+    "public.skill_package_deletions": {
+      "name": "skill_package_deletions",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "company_id": {
+          "name": "company_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider": {
+          "name": "provider",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "archive_key": {
+          "name": "archive_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "manifest_key": {
+          "name": "manifest_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "delete_after": {
+          "name": "delete_after",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "skill_package_deletions_due_idx": {
+          "name": "skill_package_deletions_due_idx",
+          "columns": [
+            {
+              "expression": "delete_after",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
     "public.company_transfer_runs": {
       "name": "company_transfer_runs",
       "schema": "",
@@ -33849,7 +34162,7 @@
             }
           ],
           "isUnique": false,
-          "where": "\"heartbeat_runs\".\"runtime_mode\" = 'native' AND \"heartbeat_runs\".\"status\" = 'cancelled'\n        AND \"heartbeat_runs\".\"runner_profile_json\"->'nativeWorkspaceSync'->>'state' = 'prepared'\n        AND \"heartbeat_runs\".\"result_json\"->'nativeCancellation'->>'dispatchState' = 'acknowledged'\n        AND (\"heartbeat_runs\".\"result_json\"->'workspaceRestoreRecovery'->>'schema' = 'paperclip.workspace-restore-recovery.v1'\n          AND \"heartbeat_runs\".\"result_json\"->>'workspaceRestoreFailure' IN ('restore_permission_denied', 'restore_lock_timeout', 'restore_unsafe_archive', 'restore_failed')) IS NOT TRUE",
+          "where": "\"heartbeat_runs\".\"runtime_mode\" = 'native' AND \"heartbeat_runs\".\"status\" = 'cancelled'\n        AND \"heartbeat_runs\".\"runner_profile_json\"->'nativeWorkspaceSync'->>'state' = 'prepared'\n        AND \"heartbeat_runs\".\"result_json\"->'nativeCancellation'->>'dispatchState' = 'acknowledged'\n        AND (\"heartbeat_runs\".\"result_json\"->'workspaceRestoreRecovery'->>'schema' = 'paperclip.workspace-restore-recovery.v1'\n          AND \"heartbeat_runs\".\"result_json\"->>'workspaceRestoreFailure' IN ('restore_permission_denied', 'restore_lock_timeout', 'restore_unsafe_archive', 'restore_invalid_metadata', 'restore_failed')) IS NOT TRUE",
           "concurrently": false,
           "method": "btree",
           "with": {}
@@ -36792,6 +37105,15 @@
             "client_request_id"
           ]
         },
+        "issue_comments_agent_client_request_uq": {
+          "name": "issue_comments_agent_client_request_uq",
+          "nullsNotDistinct": false,
+          "columns": [
+            "issue_id",
+            "author_agent_id",
+            "client_request_id"
+          ]
+        },
         "issue_comments_company_id_uq": {
           "name": "issue_comments_company_id_uq",
           "nullsNotDistinct": false,
@@ -51261,6 +51583,195 @@
       "checkConstraints": {},
       "isRLSEnabled": false
     },
+    "public.sandbox_creation_operations": {
+      "name": "sandbox_creation_operations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "company_id": {
+          "name": "company_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "environment_id": {
+          "name": "environment_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "original_environment_id": {
+          "name": "original_environment_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "run_id": {
+          "name": "run_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "request_key": {
+          "name": "request_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'run'"
+        },
+        "issue_id": {
+          "name": "issue_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "execution_workspace_id": {
+          "name": "execution_workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "provider": {
+          "name": "provider",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "plugin_id": {
+          "name": "plugin_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "driver_key": {
+          "name": "driver_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "state": {
+          "name": "state",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "config": {
+          "name": "config",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "lease_id": {
+          "name": "lease_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "next_attempt_at": {
+          "name": "next_attempt_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "sandbox_creation_operations_pending_deadline_idx": {
+          "name": "sandbox_creation_operations_pending_deadline_idx",
+          "columns": [
+            {
+              "expression": "next_attempt_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "where": "\"sandbox_creation_operations\".\"state\" = 'pending'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "sandbox_creation_operations_owner_idx": {
+          "name": "sandbox_creation_operations_owner_idx",
+          "columns": [
+            {
+              "expression": "company_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "original_environment_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "run_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "request_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "sandbox_creation_operations_environment_id_environments_id_fk": {
+          "name": "sandbox_creation_operations_environment_id_environments_id_fk",
+          "tableFrom": "sandbox_creation_operations",
+          "tableTo": "environments",
+          "columnsFrom": [
+            "environment_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
     "public.secret_access_events": {
       "name": "secret_access_events",
       "schema": "",

packages/db/src/migrations/meta/_journal.json

@@ -2920,6 +2920,13 @@
       "when": 1793395364937,
       "tag": "0418_curved_lady_mastermind",
       "breakpoints": true
+    },
+    {
+      "idx": 419,
+      "version": "7",
+      "when": 1793400383797,
+      "tag": "0419_slippery_impossible_man",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/issue_comments.ts

@@ -49,6 +49,7 @@ export const issueComments = pgTable(
   },
   (table) => ({
     clientRequestUq: unique("issue_comments_client_request_uq").on(table.issueId, table.authorUserId, table.clientRequestId),
+    agentClientRequestUq: unique("issue_comments_agent_client_request_uq").on(table.issueId, table.authorAgentId, table.clientRequestId),
     companyIdUq: unique("issue_comments_company_id_uq").on(table.companyId, table.id),
     issueIdx: index("issue_comments_issue_idx").on(table.issueId),
     reviewResponseReceiptIdx: index("issue_comments_review_response_receipt_idx").on(

packages/paperclip-runner/generated/capability/semantic-tool-contracts.json

@@ -1 +1 @@
-[{"annotations":{"exposure":"always","operationId":"get_task_context","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the active task and actor, including the exact approved Markdown revision when this issue has an accepted plan.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"get_task_context","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"get_task_history","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded comments on the active task.","inputSchema":{"additionalProperties":false,"properties":{"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":[],"type":"object"},"name":"get_task_history","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_documents","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"List revisioned documents on the active task.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"list_documents","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"read_document","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the current revision of one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable issue-document key.","maxLength":120,"minLength":1,"type":"string"}},"required":["key"],"type":"object"},"name":"read_document","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_document_revisions","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded revision history for one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable issue-document key.","maxLength":120,"minLength":1,"type":"string"},"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":["key"],"type":"object"},"name":"list_document_revisions","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"report_progress","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append a durable progress comment to the active task.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Multiline progress update.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"report_progress","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"answer_status_question","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append the answer to a status-only wake without changing task disposition.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Concise status answer.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"answer_status_question","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"write_document","requiredClaimLine truncated
+[{"annotations":{"exposure":"always","operationId":"get_task_context","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the active task and actor, including the exact approved Markdown revision when this issue has an accepted plan.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"get_task_context","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"get_task_history","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded comments on the active task.","inputSchema":{"additionalProperties":false,"properties":{"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":[],"type":"object"},"name":"get_task_history","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_documents","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"List revisioned documents on the active task.","inputSchema":{"additionalProperties":false,"properties":{},"required":[],"type":"object"},"name":"list_documents","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"read_document","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read the current revision of one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable issue-document key.","maxLength":120,"minLength":1,"type":"string"}},"required":["key"],"type":"object"},"name":"read_document","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"list_document_revisions","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Read bounded revision history for one active-task document.","inputSchema":{"additionalProperties":false,"properties":{"key":{"description":"Stable issue-document key.","maxLength":120,"minLength":1,"type":"string"},"limit":{"default":50,"maximum":200,"minimum":1,"type":"integer"}},"required":["key"],"type":"object"},"name":"list_document_revisions","outputSchema":{"additionalProperties":true,"type":"object"}},{"annotations":{"exposure":"always","operationId":"report_progress","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append a durable progress comment to the active task.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Multiline progress update.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"report_progress","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"answer_status_question","requiredClaims":[],"semanticContract":"paperclip.semantic-tool.v1","version":1},"description":"Append the answer to a status-only wake without changing task disposition.","inputSchema":{"additionalProperties":false,"properties":{"body":{"description":"Concise status answer.","maxLength":20000,"minLength":1,"type":"string"},"idempotencyKey":{"description":"Caller-stable retry key.","maxLength":240,"minLength":1,"type":"string"}},"required":["idempotencyKey","body"],"type":"object"},"name":"answer_status_question","outputSchema":{"additionalProperties":false,"properties":{"commandId":{"description":"Stable command identifier.","maxLength":200,"minLength":1,"type":"string"},"disposition":{"enum":["applied","duplicate"]},"entityRefs":{"description":"Entities affected by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"scheduledWakeIds":{"description":"Wake identifiers scheduled by the operation.","items":{"minLength":1,"type":"string"},"maxItems":200,"type":"array","uniqueItems":true},"stateRevision":{"minimum":0,"type":"integer"}},"required":["commandId","disposition","stateRevision","entityRefs","scheduledWakeIds"],"type":"object"}},{"annotations":{"exposure":"always","operationId":"write_document","requiredClaimLine truncated

packages/paperclip-runner/generated/semantic-action-catalog.json

@@ -533,6 +533,45 @@
     "title": "Report durable progress",
     "version": 1
   },
+  {
+    "allowedModes": [
+      "standard"
+    ],
+    "description": "Send a Markdown message directly to your own persistent chat with this task's responsible human. The destination is automatic. Use for requested digests and proactive task updates; report_progress writes to this task and comment_on_task writes to a chosen task. This sends no message to other agents, starts no chat run, and changes no task status. Reuse idempotencyKey on retries.",
+    "effect": "write",
+    "inputSchema": {
+      "additionalProperties": false,
+      "properties": {
+        "body": {
+          "description": "The message the human should see.",
+          "maxLength": 20000,
+          "minLength": 1,
+          "type": "string"
+        },
+        "idempotencyKey": {
+          "description": "Stable key for this message within the source task, including across run retries.",
+          "maxLength": 240,
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "body",
+        "idempotencyKey"
+      ],
+      "type": "object"
+    },
+    "operationId": "send_chat_message",
+    "outputSchema": {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    "placement": "always",
+    "requiredClaims": [],
+    "schema": "paperclip.semantic-action.v1",
+    "title": "Send message to your chat",
+    "version": 1
+  },
   {
     "allowedModes": [
       "standard",

packages/paperclip-runner/protocol/fixtures/evals/native-execution-seeded.json

@@ -24,7 +24,7 @@
     "prpVersion": 1,
     "nativeExecutionVersion": 1,
     "catalogVersion": 1,
-    "catalogSha256": "sha256:015531b07c9906c6edfa6029890cc7b2c69435c1c0c37432ffe21459e6f15c43",
+    "catalogSha256": "sha256:bb6aec4a12397e82d4f881fbce993e796cb8e8cc6852b29b308fc01ade7ef3d2",
     "driverContractVersion": 1,
     "driverKind": "paperclip-deterministic",
     "driverVersion": "1.0.0"

packages/paperclip-runner/protocol/manifest.json

@@ -180,7 +180,7 @@
     },
     {
       "path": "fixtures/evals/native-execution-seeded.json",
-      "sha256": "0b878d30ad4b5514a14f7387c3792662cbfeebc7149188ffe304197e41c20e40",
+      "sha256": "810659b1b73ed62e70598bee5cc693d5632471c0f457788167f9b8eecb0d0022",
       "expectation": "accept",
       "compatibilityCase": "canonical"
     },

packages/paperclip-runner/spec/capability/protocol-coverage.json

@@ -7,7 +7,7 @@
     "src/scenarios/scenario-plan.ts"
   ],
   "counts": {
-    "actions": 69,
+    "actions": 70,
     "legacyRequirements": 106
   },
   "actions": [
@@ -106,6 +106,25 @@
         "src/scenarios/scenario-explorer.test.ts::renders every scenario with exposure, control plane, authorization, diff, and parity"
       ]
     },
+    {
+      "id": "send_chat_message",
+      "ownership": "always_agent_tool",
+      "surfaces": [
+        "live"
+      ],
+      "legacyAliases": [],
+      "contractCase": "protocol-action:send_chat_message",
+      "contractOwner": "src/catalog/protocol-action-contracts.test.ts::send_chat_message has a schema-valid canonical example and every declared projection",
+      "legacyBehavioralCases": [],
+      "deterministicCases": [
+        "protocol-action:send_chat_message"
+      ],
+      "legacyRequirementCases": [],
+      "deterministicOwners": [
+        "src/catalog/protocol-action-contracts.test.ts::send_chat_message has a schema-valid canonical example and every declared projection",
+        "src/scenarios/scenario-explorer.test.ts::renders every scenario with exposure, control plane, authorization, diff, and parity"
+      ]
+    },
     {
       "id": "set_task_monitor",
       "ownership": "optional_agent_tool",

packages/paperclip-runner/spec/operation-groups/source.json

@@ -262,12 +262,13 @@
       "owner": "always tools",
       "operationIds": [
         "get_task_history",
-        "report_progress"
+        "report_progress",
+        "send_chat_message"
       ],
       "controlPlaneOperationIds": [
         "append_audit_record"
       ],
-      "realSurface": "issue comment list/get/create routes",
+      "realSurface": "issue comment list/get/create routes and own-agent chat messaging service",
       "mockStateDomains": [
         "task",
         "comments",
@@ -275,8 +276,8 @@
         "idempotency",
         "audit"
       ],
-      "prpEvidence": "bounded read result or idempotent comment-write receipt plus audit reference",
-      "gap": "Active-task binding is unbound; cross-task comment mutation is deliberately outside V1."
+      "prpEvidence": "bounded read result, idempotent progress receipt, or persisted proactive chat comment with source task/run provenance",
+      "gap": "Proactive chat delivery is bound to the running agent and responsible human; arbitrary chat destinations are unsupported. Other comment/history binding gaps remain recorded per operation."
     },
     {
       "id": "se",

packages/paperclip-runner/spec/paperclip-agent-operation-groups.md

@@ -6,7 +6,7 @@ Status: canonical explanatory contract for the Paperclip runner V1 surface.
 
 This document keeps three independent meanings of **group** separate. PRP families describe wire evidence and controller commands; capability placement decides who owns an operation; behavioral eval groups organize the 106 scenario corpus. None of the three axes can be used as a substitute for another.
 
-The generated totals are **107 PRP events in 32 event families**, **18 controller commands in 7 command families**, **10 control-plane operations**, **69 reconciled semantic operations** (18 always, 51 optional), and **106 scenarios in 16 behavior groups**.
+The generated totals are **107 PRP events in 32 event families**, **18 controller commands in 7 command families**, **10 control-plane operations**, **70 reconciled semantic operations** (19 always, 51 optional), and **106 scenarios in 16 behavior groups**.
 
 ## Axis 1: PRP v1 event and command families
 
@@ -84,9 +84,9 @@ Placement has exactly three outcomes:
 | `schedule_blocker_wake` | Dependency-resolution wake scheduling. |
 | `reconcile_run` | Work assessment, terminal status arbitration, and recovery reconciliation. |
 
-### Always-agent operations (18)
+### Always-agent operations (19)
 
-`answer_status_question`, `block_task`, `finish_task`, `get_agent_instruction_history`, `get_task_context`, `get_task_history`, `inspect_operation_result`, `list_document_revisions`, `list_documents`, `read_agent_instructions`, `read_document`, `register_deliverable`, `report_progress`, `request_human_input`, `request_review`, `restore_agent_instructions`, `update_agent_instructions`, `write_document`.
+`answer_status_question`, `block_task`, `finish_task`, `get_agent_instruction_history`, `get_task_context`, `get_task_history`, `inspect_operation_result`, `list_document_revisions`, `list_documents`, `read_agent_instructions`, `read_document`, `register_deliverable`, `report_progress`, `request_human_input`, `request_review`, `restore_agent_instructions`, `send_chat_message`, `update_agent_instructions`, `write_document`.
 
 ### Optional operations (51) and grant groups (14)
 
@@ -172,6 +172,7 @@ Grant groups are documentation/exposure bundles, not additional authority. The o
 | `search_api` | `optional_agent_tool` | `api:discover` | `standard`<br>`ask`<br>`planning`<br>`skill_test` | `read` | `none` | no | inline/no mapping | `live`<br>`live_codex` | `PaperclipRunnerToolAuthority`<br>Authenticated PRP tool input/result and existing HTTP route authorization/activity records.<br>catalog PRP status: `bound` |
 | `search_tasks` | `optional_agent_tool` | `discovery:tasks:read` | `standard`<br>`ask`<br>`planning`<br>`skill_test` | `read` | `none` | no | `snapshot_read:company_tasks` | `scenario` + `live`<br>`live_codex` | `unbound`<br>read projection surfaced via a tool-result item event; no control-plane state diff<br>catalog PRP status: `audit_pending` |
 | `select_workspace` | `optional_agent_tool` | none | `standard`<br>`skill_test` | `write` | `required` | no | inline/no mapping | `live`<br>`live_codex` | `PaperclipRunnerToolAuthority`<br>Authenticated task workspace routes and durable selection/repository receipts.<br>catalog PRP status: `bound` |
+| `send_chat_message` | `always_agent_tool` | none | `standard` | `task_write` | `required` | no | inline/no mapping | `live`<br>`live_codex` | `sendAgentChatMessage`<br>Attributed chat comment and transactional delivery receipt without execution or task disposition changes.<br>catalog PRP status: `bound` |
 | `set_dependencies` | `optional_agent_tool` | `dependencies:write` | `standard`<br>`skill_test` | `company_write` | `required` | no | `semantic_command:set_dependencies` | `scenario` + `live`<br>`live_codex` | `issues.update.blockedByIssueIds`<br>semantic-operation item event plus company-entity state diff and audit record<br>catalog PRP status: `bound` |
 | `set_task_monitor` | `optional_agent_tool` | none | `standard` | `task_write` | `required` | no | inline/no mapping | `live`<br>`live_codex` | `prepareIssueMonitorUpdate`<br>Transactional persisted issue monitor, audit activity and idempotent run receipt.<br>catalog PRP status: `bound` |
 | `set_task_title` | `optional_agent_tool` | none | `standard`<br>`ask`<br>`planning`<br>`skill_test` | `task_write` | `required` | no | inline/no mapping | `live`<br>`live_codex` | `setIssueTitle`<br>Run-bound title update and transactional activity record.<br>catalog PRP status: `bound` |
@@ -196,7 +197,7 @@ Behavior groups describe expected outcomes and trajectories. They do not grant t
 | [`hb` — Heartbeat](#behavior-group-hb-heartbeat) | control plane + always tools | `get_task_context`<br>`set_task_title` | `select_work`<br>`enforce_budget` | agent identity, inbox-lite, heartbeat context, budget and active-issue services | `company`<br>`actor`<br>`wake`<br>`task`<br>`budget`<br>`run` | 5 | runner/session/run context plus bounded task-context tool results | Production semantic binding is unbound; identity and work selection remain injected/control-plane-owned. |
 | [`co` — Checkout](#behavior-group-co-checkout) | control plane | none | `checkout_task` | POST /api/issues/:id/checkout and execution-lock services | `task`<br>`actor`<br>`run`<br>`idempotency`<br>`fault` | 6 | run preparation and issue-status decision evidence with checkout receipt | Intentionally no model tool; the production checkout receipt still needs the additive semantic-receipt envelope. |
 | [`st` — Status](#behavior-group-st-status) | always tools + control-plane arbitration | `answer_status_question`<br>`finish_task`<br>`block_task`<br>`request_review` | `reconcile_run`<br>`append_audit_record` | issue PATCH, review/liveness policy, and native finalization arbitration | `task`<br>`comments`<br>`interactions`<br>`blockers`<br>`audit`<br>`run` | 8 | semantic operation receipt, work assessment, issue-status decision, and terminal causality | Production semantic binding and additive typed operation/conflict receipts remain unimplemented. |
-| [`cm` — Comments](#behavior-group-cm-comments) | always tools | `get_task_history`<br>`report_progress` | `append_audit_record` | issue comment list/get/create routes | `task`<br>`comments`<br>`actor`<br>`idempotency`<br>`audit` | 6 | bounded read result or idempotent comment-write receipt plus audit reference | Active-task binding is unbound; cross-task comment mutation is deliberately outside V1. |
+| [`cm` — Comments](#behavior-group-cm-comments) | always tools | `get_task_history`<br>`report_progress`<br>`send_chat_message` | `append_audit_record` | issue comment list/get/create routes and own-agent chat messaging service | `task`<br>`comments`<br>`actor`<br>`idempotency`<br>`audit` | 6 | bounded read result, idempotent progress receipt, or persisted proactive chat comment with source task/run provenance | Proactive chat delivery is bound to the running agent and responsible human; arbitrary chat destinations are unsupported. Other comment/history binding gaps remain recorded per operation. |
 | [`se` — Search](#behavior-group-se-search) | optional discovery tools | `search_tasks`<br>`list_agents`<br>`get_agent`<br>`list_projects`<br>`list_goals`<br>`list_project_repositories` | none | company issue search and agent/project/goal list/get routes | `company`<br>`task`<br>`actor`<br>`project`<br>`goal` | 4 | bounded redacted read projections through tool-result item events | Goal operations remain scenario-only. Project and repository discovery contracts are delivered by the live server authority; they are not implemented by the mock command dispatcher. |
 | [`su` — Subtasks](#behavior-group-su-subtasks) | optional delegation tools | `create_task`<br>`reassign_task`<br>`hire_agent`<br>`handoff_case` | `route_wake` | company issue create, child issue, guarded reassignment, and wake services | `company`<br>`task`<br>`actor`<br>`blockers`<br>`wake`<br>`audit` | 4 | company/task state diff, audit reference, and continuation wake evidence | create_task is production-bound to ordinary active-issue child creation with assignment, dependency-ready wake, company checks, child limits, and durable source-scoped idempotency. handoff_case is live-only: the dedicated case service moves the same primary task after source execution settles, or records completion intent subject to ordinary completion gates; legacy scenarios do not claim that coverage. |
 | [`bl` — Blockers](#behavior-group-bl-blockers) | always/optional tools + control plane | `block_task`<br>`set_dependencies` | `schedule_blocker_wake`<br>`route_wake` | issue relations, blocker projection, liveness validation, and blocker wake services | `task`<br>`blockers`<br>`wake`<br>`actor`<br>`audit`<br>`fault` | 5 | dependency diff, block receipt, attention routing, and issue-status decision | set_dependencies is production-bound for the active issue; block_task remains unbound, and cancelled-blocker receipts still need typed additive evidence. |
@@ -482,10 +483,10 @@ Current responsibility-based paths are normative. Numbered `phase-*` or mileston
 ### Catalog split and deliberate replacement
 
 - Scenario/eval catalog: **40** operations.
-- Live dispatcher catalog: **57** operations.
-- Shared: **28**; union/canonical authority: **69**.
+- Live dispatcher catalog: **58** operations.
+- Shared: **28**; union/canonical authority: **70**.
 - Scenario-only: `administer_company`, `export_company`, `inspect_operation_result`, `list_cases`, `list_company_skills`, `list_goals`, `list_routines`, `list_secret_metadata`, `manage_routine`, `read_secret_value`, `sync_company_skills`, `upsert_case`.
-- Live-only: `call_api`, `create_case`, `create_project`, `create_workflow`, `get_agent`, `get_agent_instruction_history`, `get_approval`, `get_approval_context`, `get_workspace`, `handoff_case`, `hire_agent`, `list_project_repositories`, `list_workflows`, `list_workspaces`, `prepare_repository`, `read_agent_instructions`, `read_case`, `read_workflow`, `restore_agent_instructions`, `schedule_wake`, `search_api`, `select_workspace`, `set_task_monitor`, `set_task_title`, `submit_complaint`, `submit_suggestion`, `update_agent_instructions`, `update_case`, `update_workflow`.
+- Live-only: `call_api`, `create_case`, `create_project`, `create_workflow`, `get_agent`, `get_agent_instruction_history`, `get_approval`, `get_approval_context`, `get_workspace`, `handoff_case`, `hire_agent`, `list_project_repositories`, `list_workflows`, `list_workspaces`, `prepare_repository`, `read_agent_instructions`, `read_case`, `read_workflow`, `restore_agent_instructions`, `schedule_wake`, `search_api`, `select_workspace`, `send_chat_message`, `set_task_monitor`, `set_task_title`, `submit_complaint`, `submit_suggestion`, `update_agent_instructions`, `update_case`, `update_workflow`.
 - The generated provider contract contains exactly the live catalog; the canonical union remains the migration authority until all scenario-only operations are either implemented, deferred, or removed by an explicit reconciliation decision.
 - `generic_api_request` stays exported only for controlled tests and cannot be cited as real-surface, mock-parity, or PRP product coverage.
 

packages/paperclip-runner/src/catalog/reconciliation.test.ts

@@ -20,9 +20,9 @@ describe("canonical semantic-catalog reconciliation authority", () => {
   it("pins the reconciled op-set relationship between the two catalogs", () => {
     const summary = capabilityCatalogReconciliation();
     expect(summary.scenarioCount).toBe(40);
-    expect(summary.liveCount).toBe(57);
+    expect(summary.liveCount).toBe(58);
     expect(summary.sharedCount).toBe(28);
-    expect(summary.unionCount).toBe(69);
+    expect(summary.unionCount).toBe(70);
     // Any operation added to or removed from either catalog without a
     // reconciliation decision changes these exact sets and fails the gate.
     expect(summary.liveOnly).toEqual([
@@ -48,6 +48,7 @@ describe("canonical semantic-catalog reconciliation authority", () => {
       "schedule_wake",
       "search_api",
       "select_workspace",
+      "send_chat_message",
       "set_task_monitor",
       "set_task_title",
       "submit_complaint",
@@ -73,7 +74,7 @@ describe("canonical semantic-catalog reconciliation authority", () => {
   });
 
   it("is the single source both catalogs derive their operation set from", () => {
-    expect(CAPABILITY_CANONICAL_OPERATIONS).toHaveLength(69);
+    expect(CAPABILITY_CANONICAL_OPERATIONS).toHaveLength(70);
     const canonicalIds = new Set(CAPABILITY_CANONICAL_OPERATIONS.map((operation) => operation.operationId));
     // Neither catalog may contain an operation absent from the canonical source.
     for (const tool of SCENARIO_CATALOG) expect(canonicalIds.has(tool.operationId)).toBe(true);
@@ -107,7 +108,7 @@ describe("canonical semantic-catalog reconciliation authority", () => {
   });
 
   it("names placement, claims, task modes, side-effect class, idempotency, redaction, mock mapping, real binding status, and PRP evidence for every operation", () => {
-    expect(CAPABILITY_CANONICAL_CATALOG).toHaveLength(69);
+    expect(CAPABILITY_CANONICAL_CATALOG).toHaveLength(70);
     for (const operation of CAPABILITY_CANONICAL_CATALOG) {
       expect(operation.placement).toMatch(/^(always|optional)_agent_tool$/);
       expect(Array.isArray(operation.requiredClaims)).toBe(true);
@@ -133,7 +134,7 @@ describe("canonical semantic-catalog reconciliation authority", () => {
   it("classifies real binding status so generic_api_request is never product coverage", () => {
     const summary = capabilityCatalogReconciliation();
     expect(summary.byRealBindingStatus).toEqual({
-      live_codex: 56,
+      live_codex: 57,
       scenario_mock: 12,
       test_only: 1,
     });

packages/paperclip-runner/src/catalog/semantic-action-catalog.test.ts

@@ -127,8 +127,9 @@ describe("semantic action catalog", () => {
       (action) => action.operationId,
     );
 
-    expect(operationIds).toHaveLength(49);
+    expect(operationIds).toHaveLength(50);
     expect(operationIds).toContain("set_task_monitor");
+    expect(operationIds).toContain("send_chat_message");
     expect(new Set(operationIds).size).toBe(operationIds.length);
     expect(operationIds).not.toContain("generic_api_request");
     expect(Object.isFrozen(PAPERCLIP_SEMANTIC_ACTION_CATALOG)).toBe(true);

packages/paperclip-runner/src/catalog/semantic-action-catalog.ts

@@ -8,6 +8,7 @@ import { prepareRepositoryAction } from "../protocol-actions/prepare-repository.
 import { setTaskMonitorInputSchema } from "../protocol-actions/set-task-monitor.js";
 import { listProjectsDescription, listProjectsInputSchema } from "../protocol-actions/list-projects.js";
 import { setTaskTitleAction } from "../protocol-actions/set-task-title.js";
+import { sendChatMessageAction } from "../protocol-actions/send-chat-message.js";
 import { reassignTaskAction } from "../protocol-actions/reassign-task.js";
 import type {
   PaperclipJsonSchema,
@@ -191,6 +192,12 @@ const descriptors: readonly PaperclipSemanticActionDescriptor[] = [
     ),
     outputSchema: operationReceipt,
   }),
+  descriptor({
+    operationId: "send_chat_message", title: "Send message to your chat",
+    description: sendChatMessageAction.documentation.description, effect: "write",
+    allowedModes: ["standard"], inputSchema: sendChatMessageAction.live.descriptor.inputSchema,
+    outputSchema: openObject,
+  }),
   descriptor({
     operationId: "answer_status_question",
     title: "Answer status question",

packages/paperclip-runner/src/catalog/semantic-action-types.ts

@@ -2,6 +2,7 @@ export type PaperclipSemanticActionId =
   | "search_api"
   | "call_api"
   | "set_task_title"
+  | "send_chat_message"
   | "set_task_monitor"
   | "get_task_context"
   | "get_task_history"

packages/paperclip-runner/src/eval/workflow-evals.test.ts

@@ -466,15 +466,15 @@ describe("workflow reports and stress traceability", () => {
       candidateFailures: 36,
     });
     expect(report.coverage).toMatchObject({
-      canonicalOperations: 69,
+      canonicalOperations: 70,
       capabilityCases: 106,
       workflows: 12,
       stressFindings: 44,
       stressExclusions: 1,
     });
-    expect(report.coverage.operations).toHaveLength(69);
+    expect(report.coverage.operations).toHaveLength(70);
     expect(report.coverage.operations).toEqual(expect.arrayContaining(
-      ["create_case", "read_case", "update_case", "handoff_case", "list_workflows", "read_workflow", "create_workflow", "update_workflow"].map(operationId =>
+      ["create_case", "read_case", "update_case", "handoff_case", "list_workflows", "read_workflow", "create_workflow", "update_workflow", "send_chat_message"].map(operationId =>
         expect.objectContaining({ operationId, workflowIds: [] })),
     ));
     expect(report.coverage.composedWorkflows).toHaveLength(12);
@@ -484,7 +484,7 @@ describe("workflow reports and stress traceability", () => {
       )?.workflowIds.length,
     ).toBeGreaterThan(0);
     expect(renderRunnerWorkflowMarkdown(report)).toContain(
-      "69 operations · 106 capability cases · 12 workflows",
+      "70 operations · 106 capability cases · 12 workflows",
     );
     expect(renderRunnerWorkflowJUnit(report)).toContain(
       'tests="36" failures="36" skipped="0"',

packages/paperclip-runner/src/protocol-actions/index.ts

@@ -4,6 +4,7 @@ import { selectWorkspaceAction } from "./select-workspace.js";
 import { prepareRepositoryAction } from "./prepare-repository.js";
 import { setTaskMonitorAction } from "./set-task-monitor.js";
 import { setTaskTitleAction } from "./set-task-title.js";
+import { sendChatMessageAction } from "./send-chat-message.js";
 import { submitComplaintAction, submitSuggestionAction } from "./submit-agent-commentary.js";
 import { readAgentInstructionsAction } from "./read-agent-instructions.js";
 import { updateAgentInstructionsAction } from "./update-agent-instructions.js";
@@ -70,6 +71,7 @@ export const PAPERCLIP_PROTOCOL_ACTIONS = deepFreezeProtocolAction([
   prepareRepositoryAction,
 
   setTaskTitleAction,
+  sendChatMessageAction,
   setTaskMonitorAction,
   submitComplaintAction,
   submitSuggestionAction,

packages/paperclip-runner/src/protocol-actions/send-chat-message.ts

@@ -0,0 +1,30 @@
+const description = "Send a Markdown message directly to your own persistent chat with this task's responsible human. The destination is automatic. Use for requested digests and proactive task updates; report_progress writes to this task and comment_on_task writes to a chosen task. This sends no message to other agents, starts no chat run, and changes no task status. Reuse idempotencyKey on retries.";
+const inputSchema = {
+  type: "object", properties: {
+    body: { type: "string", minLength: 1, maxLength: 20000, description: "The message the human should see." },
+    idempotencyKey: { type: "string", minLength: 1, maxLength: 240, description: "Stable key for this message within the source task, including across run retries." },
+  }, required: ["body", "idempotencyKey"], additionalProperties: false,
+} as const;
+
+export const sendChatMessageAction = {
+  id: "send_chat_message",
+  canonical: {
+    operationId: "send_chat_message", surfaces: ["live"], placement: "always_agent_tool", optionalGroup: null,
+    requiredClaims: [], taskModes: ["standard"], sideEffectClass: "task_write", idempotency: "required",
+    disabledByDefault: false, realBindingStatus: "live_codex", realServiceBinding: "sendAgentChatMessage",
+    prpEvidence: "Attributed chat comment and transactional delivery receipt without execution or task disposition changes.",
+    prpBindingStatus: "bound", legacyAliases: [],
+  },
+  documentation: { title: "Send message to your chat", description, note: null },
+  examples: {
+    call: { operationId: "send_chat_message", input: { body: "Three PRs need review.", idempotencyKey: "morning-digest" } },
+    scenarioCall: null,
+    success: { ok: true, operationId: "send_chat_message", result: { commentId: "comment-1", conversationId: "chat-1", sourceTaskId: "task-1", chatUrl: "/PC/chats/kodi", replayed: false } },
+  },
+  live: { order: 51, descriptor: {
+    schema: "paperclip.semantic-tool.v1", operationId: "send_chat_message", version: 1,
+    title: "Send message to your chat", description, exposure: "always", requiredClaims: [],
+    allowedModes: ["standard"], inputSchema, outputSchema: { type: "object", additionalProperties: true },
+  } },
+  scenario: null,
+} as const;

packages/paperclip-runner/src/semantic-tools/discovery.ts

@@ -21,6 +21,7 @@ const MAX_DISCOVERY_RESULTS = 10;
 
 const NAMESPACE: Readonly<Record<CapabilitySemanticOperationId, string>> = Object.freeze({
   set_task_title: "active_task",
+  send_chat_message: "active_task",
   handoff_case: "delegation",
   read_case: "delegation", update_case: "delegation",
   create_case: "delegation",

packages/paperclip-runner/src/semantic-tools/paperclip-discovery.ts

@@ -13,6 +13,7 @@ import type {
 const NAMESPACE: Readonly<Record<PaperclipSemanticActionId, string>> =
   Object.freeze({
     set_task_title: "active_task",
+    send_chat_message: "active_task",
   set_task_monitor: "continuation",
     search_api: "api_fallback",
     call_api: "api_fallback",

packages/paperclip-runner/src/semantic-tools/semantic-tools.test.ts

@@ -113,7 +113,8 @@ describe("Capability semantic catalog and authorization", () => {
   it("publishes a stable narrow catalog without credentials or control-plane-owned tools", () => {
     const names = CAPABILITY_SEMANTIC_TOOL_CATALOG.map((tool) => tool.operationId);
     expect(new Set(names).size).toBe(names.length);
-    expect(names).toHaveLength(57);
+    expect(names).toHaveLength(58);
+    expect(names).toContain("send_chat_message");
     expect(names).toEqual(expect.arrayContaining(["list_workflows", "read_workflow", "create_workflow", "update_workflow"]));
     expect(names).toContain("set_task_monitor");
     expect(names).toEqual(expect.arrayContaining(["submit_complaint", "submit_suggestion"]));

packages/paperclip-runner/src/semantic-tools/types.ts

@@ -19,6 +19,7 @@ export type CapabilitySemanticOperationId =
   | "search_api"
   | "call_api"
   | "set_task_title"
+  | "send_chat_message"
   | "set_task_monitor"
   | "get_task_context"
   | "get_task_history"

packages/shared/src/index.ts

@@ -1993,6 +1993,8 @@ export {
   issueCommentMetadataSectionSchema,
   issueCommentMetadataSchema,
   addIssueCommentSchema,
+  sendChatMessageSchema,
+  markIssueReadSchema,
   issueThreadInteractionStatusSchema,
   issueThreadInteractionKindSchema,
   issueThreadInteractionContinuationPolicySchema,

packages/shared/src/types/issue.ts

@@ -1178,6 +1178,12 @@ export interface IssueCommentMetadataSection {
 
 export interface IssueCommentMetadata {
   version: 1;
+  chatMessage?: {
+    sourceTaskId: string;
+    sourceTaskIdentifier: string;
+    sourceRunId: string;
+    contentHash: string;
+  };
   /** Producer-classified diagnostics; task interruption UI owns system repair. */
   recoveryResponsibility?: "system" | "user";
   /** Inbound channel attribution; never an authorization input. */

packages/shared/src/validators/index.ts

@@ -460,6 +460,8 @@ export {
   issueCommentMetadataSectionSchema,
   issueCommentMetadataSchema,
   addIssueCommentSchema,
+  sendChatMessageSchema,
+  markIssueReadSchema,
   issueThreadInteractionStatusSchema,
   issueThreadInteractionKindSchema,
   issueThreadInteractionCanonicalResolverPolicySchema,

packages/shared/src/validators/issue.ts

@@ -1101,6 +1101,12 @@ export const issueCommentMetadataSectionSchema = z
 export const issueCommentMetadataSchema = z
   .object({
     version: z.literal(1),
+    chatMessage: z.object({
+      sourceTaskId: z.uuid(),
+      sourceTaskIdentifier: z.string().min(1).max(80),
+      sourceRunId: z.uuid(),
+      contentHash: z.string().regex(/^[a-f0-9]{64}$/),
+    }).strict().optional(),
     recoveryResponsibility: z.enum(["system", "user"]).optional(),
     sourceChannel: z.enum(CHAT_PROVIDERS).optional(),
     sourceRunId: z.string().guid().nullable().optional(),
@@ -1125,6 +1131,13 @@ export const issueCommentMetadataSchema = z
 
 export type IssueCommentMetadata = z.infer<typeof issueCommentMetadataSchema>;
 
+export const sendChatMessageSchema = z.object({
+  body: multilineTextSchema.pipe(z.string().trim().min(1).max(20000)),
+  idempotencyKey: z.string().trim().min(1).max(240),
+}).strict();
+
+export const markIssueReadSchema = z.object({ throughCommentId: z.uuid().optional() }).strict();
+
 export const addIssueCommentSchema = z.object({
   clientRequestId: z.string().uuid().optional(),
   body: multilineTextSchema.pipe(z.string().min(1)),

server/src/__tests__/agent-chat-messages.test.ts

@@ -0,0 +1,405 @@
+import { createHash, randomUUID } from "node:crypto";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { eq, sql } from "drizzle-orm";
+import { activityLog, agentApiKeys, agents, authUsers, chatCompletionDeliveries, chatTaskHandoffs, companyMemberships, heartbeatRuns, issueComments, issueThreadInteractions, issues, projects } from "@paperclipai/db";
+import type { AgentApiKeyScope } from "@paperclipai/shared";
+import { createLocalAgentJwt } from "../agent-auth-jwt.js";
+import { sendAgentChatMessage } from "../services/agent-chat-messages.js";
+import { withConversationReadState } from "../services/agent-chat-read-state.js";
+import { instanceSettingsService } from "../services/instance-settings.js";
+import { issueService } from "../services/issues.js";
+import { activityService } from "../services/activity.js";
+import { recordAcceptedChatHandoff } from "../services/chat-completion-delivery.js";
+import { conversationReplay, deliverConversationComments, undeliveredConversationComments } from "../services/agent-conversations.js";
+import { PaperclipRunnerToolAuthority } from "../services/native-runtime/paperclip-runner-tool-authority.js";
+import { CROSS_ISSUE_INFLUENCE_LIMIT } from "../services/cross-issue-influence-limit.js";
+import { startRunnerApiTestServer } from "./helpers/runner-api-server.js";
+import { recoveryPostgresSupport as support } from "./helpers/recovery-postgres.js";
+
+(support.supported ? describe : describe.skip)("proactive agent chat messages", () => {
+  let server: Awaited<ReturnType<typeof startRunnerApiTestServer>>;
+  const originalSecret = process.env.PAPERCLIP_AGENT_JWT_SECRET;
+  beforeAll(async () => {
+    process.env.PAPERCLIP_AGENT_JWT_SECRET = randomUUID();
+    server = await startRunnerApiTestServer({ humanSessions: true });
+    await instanceSettingsService(server.db).updateExperimental({ enableAgentChat: true });
+  }, 60_000);
+  afterAll(async () => {
+    await server?.close();
+    if (originalSecret === undefined) delete process.env.PAPERCLIP_AGENT_JWT_SECRET;
+    else process.env.PAPERCLIP_AGENT_JWT_SECRET = originalSecret;
+  });
+  const fixture = () => server.fixture({ connectionScenario: "fresh", apiToolsEnabled: false, disableWakeOnDemand: true });
+  type Fixture = Awaited<ReturnType<typeof fixture>>;
+  const input = { body: "## Morning review\n\nThree PRs need your review.", idempotencyKey: "morning-pr-digest" };
+  const send = (f: Fixture, value: unknown = input) => sendAgentChatMessage(server.db, f, value);
+  const httpSend = (f: Fixture, value: unknown = input, keyScope: AgentApiKeyScope = { kind: "standard" }, authorizingUserId?: string) => fetch(`${server.apiUrl}/api/agents/me/chat/messages`, {
+    method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${createLocalAgentJwt(f.agentId, f.companyId, "paperclip_runner", f.runId, f.responsibleUserId, keyScope, authorizingUserId)}` },
+    body: JSON.stringify(value),
+  });
+  const apiKey = async (f: Fixture, scopeConfig: AgentApiKeyScope = { kind: "standard" }) => {
+    const token = `pcp_${randomUUID()}`;
+    const [key] = await server.db.insert(agentApiKeys).values({ companyId: f.companyId, agentId: f.agentId, name: "Chat delivery test",
+      responsibleUserId: f.responsibleUserId, scopeConfig, keyHash: createHash("sha256").update(token).digest("hex") }).returning();
+    return { ...key, token };
+  };
+  const keySend = (f: Fixture, token: string, value: unknown = input) => fetch(`${server.apiUrl}/api/agents/me/chat/messages`, {
+    method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}`, "x-paperclip-run-id": f.runId },
+    body: JSON.stringify(value),
+  });
+  const spendInfluence = (f: Fixture, count: number) => server.db.insert(activityLog).values(Array.from({ length: count }, (_, index) => ({
+    companyId: f.companyId, actorType: "agent" as const, actorId: f.agentId, agentId: f.agentId, runId: f.runId,
+    action: "issue.cross_issue_influence_observed", entityType: "issue", entityId: f.issueId,
+    details: { kind: ["comment", "update", "interaction_resolution"][index % 3] },
+  })));
+
+  it.each(["native", "http"])("enforces the shared run cap for %s delivery without creating an empty chat", async transport => {
+    const f = await fixture();
+    await spendInfluence(f, CROSS_ISSUE_INFLUENCE_LIMIT);
+    if (transport === "native") {
+      await expect(f.authority.execute({ tool: "send_chat_message", arguments: input, callId: randomUUID() }))
+        .rejects.toMatchObject({ status: 429, details: { code: "cross_issue_influence_cap_exceeded", cap: CROSS_ISSUE_INFLUENCE_LIMIT } });
+    } else {
+      const response = await httpSend(f);
+      expect(response.status, await response.clone().text()).toBe(429);
+      expect(await response.json()).toMatchObject({ details: { code: "cross_issue_influence_cap_exceeded", cap: CROSS_ISSUE_INFLUENCE_LIMIT } });
+    }
+    const snapshot = await f.snapshot();
+    expect(snapshot.comments).toEqual([]);
+    expect(snapshot.issues.filter(issue => issue.conversationAgentId)).toEqual([]);
+    expect(snapshot.activity).toHaveLength(CROSS_ISSUE_INFLUENCE_LIMIT);
+  });
+
+  it("charges a committed message once across retries, recovery and conflicting content", async () => {
+    const f = await fixture(), receipt = (await send(f))!;
+    expect((await httpSend(f)).status).toBe(200);
+    expect(await f.authority.recover({ tool: "send_chat_message", arguments: input, callId: randomUUID() }))
+      .toMatchObject({ result: { commentId: receipt.commentId, replayed: true } });
+    expect((await httpSend(f, { ...input, body: "Different content" })).status).toBe(409);
+    expect(await f.authority.recover({ tool: "send_chat_message", arguments: { ...input, idempotencyKey: "not-committed" }, callId: randomUUID() })).toBeNull();
+    expect((await f.snapshot()).activity.filter(row => row.action === "issue.cross_issue_influence_observed")).toHaveLength(1);
+    expect((await f.snapshot()).comments).toHaveLength(1);
+  });
+
+  it("cannot race native and HTTP delivery past the shared final slot", async () => {
+    const f = await fixture();
+    await spendInfluence(f, CROSS_ISSUE_INFLUENCE_LIMIT - 1);
+    const outcomes = await Promise.all([
+      f.authority.execute({ tool: "send_chat_message", arguments: { ...input, idempotencyKey: "native-last-slot" }, callId: randomUUID() })
+        .then(() => 201, error => error.status),
+      httpSend(f, { ...input, idempotencyKey: "http-last-slot" }).then(response => response.status),
+    ]);
+    expect(outcomes.sort()).toEqual([201, 429]);
+    const snapshot = await f.snapshot();
+    expect(snapshot.activity.filter(row => row.action === "issue.cross_issue_influence_observed")).toHaveLength(CROSS_ISSUE_INFLUENCE_LIMIT);
+    expect(snapshot.comments).toHaveLength(1);
+    expect(snapshot.issues.filter(issue => issue.conversationAgentId)).toHaveLength(1);
+  });
+
+  it("supports standard task API keys without changing agent and run attribution", async () => {
+    const f = await fixture(), key = await apiKey(f);
+    const response = await keySend(f, key.token);
+    expect(response.status, await response.clone().text()).toBe(201);
+    expect((await f.snapshot()).activity).toContainEqual(expect.objectContaining({ action: "issue.comment_added",
+      actorId: f.agentId, agentId: f.agentId, runId: f.runId, responsibleUserId: f.responsibleUserId }));
+  });
+
+  it("preserves an external authorizer's current access intersection", async () => {
+    const f = await fixture();
+    expect((await httpSend(f, input, { kind: "standard" }, randomUUID())).status).toBe(403);
+    await expect(sendAgentChatMessage(server.db, { ...f, authorizingUserId: randomUUID() }, input)).rejects.toMatchObject({ status: 403 });
+    expect((await f.snapshot()).issues.filter(issue => issue.conversationAgentId)).toEqual([]);
+    expect((await f.snapshot()).comments).toEqual([]);
+  });
+
+  it("keeps skill-test JWT and API-key scopes confined to their own task", async () => {
+    const f = await fixture(), scope = { kind: "skill_test", issueId: f.issueId } as const;
+    const key = await apiKey(f, scope);
+    expect((await httpSend(f, input, scope)).status).toBe(403);
+    expect((await keySend(f, key.token)).status).toBe(403);
+    expect((await f.snapshot()).issues.filter(issue => issue.conversationAgentId)).toEqual([]);
+    expect((await f.snapshot()).comments).toEqual([]);
+  });
+
+  it.each(["admitted", "legacy", "saved-task"])("retains a persisted %s skill-test run boundary after task mode changes", async kind => {
+    const f = await fixture();
+    const contextSnapshot = kind === "admitted" ? { paperclipAgentJwtScope: { kind: "skill_test", issueId: f.issueId } }
+      : kind === "legacy" ? { paperclipSkillTest: { id: randomUUID() } }
+      : { paperclipIssue: { id: f.issueId, workMode: "skill_test" } };
+    await server.db.update(heartbeatRuns).set({ contextSnapshot }).where(eq(heartbeatRuns.id, f.runId));
+    await server.db.update(issues).set({ workMode: "skill_test" }).where(eq(issues.id, f.issueId));
+    await server.db.update(issues).set({ workMode: "standard" }).where(eq(issues.id, f.issueId));
+    expect((await httpSend(f)).status).toBe(403);
+    await expect(sendAgentChatMessage(server.db, f, input, { receiptOnly: true })).rejects.toThrow(/skill.test/i);
+    expect((await f.snapshot()).issues.filter(issue => issue.conversationAgentId)).toEqual([]);
+    expect((await f.snapshot()).comments).toEqual([]);
+  });
+
+  it("does not let task-bridge credentials publish outside their admitted task", async () => {
+    const f = await fixture(), key = await apiKey(f, { kind: "task_bridge", parentIssueId: f.issueId });
+    expect((await keySend(f, key.token)).status).toBe(403);
+    expect((await f.snapshot()).issues.filter(issue => issue.conversationAgentId)).toEqual([]);
+  });
+
+  it.each(["revoked", "narrowed", "responsible-human"])("rechecks a %s API key after waiting for the destination", async kind => {
+    const f = await fixture(), receipt = (await send(f))!, key = await apiKey(f);
+    let unlock!: () => void, ready!: (pid: number) => void;
+    const locked = new Promise<number>(resolve => { ready = resolve; });
+    const release = new Promise<void>(resolve => { unlock = resolve; });
+    const gate = server.db.transaction(async tx => {
+      const [{ pid }] = await tx.execute(sql<{ pid: number }>`select pg_backend_pid() as pid`);
+      await tx.select({ id: issues.id }).from(issues).where(eq(issues.id, receipt.conversationId)).for("update");
+      ready(pid); await release;
+    });
+    const pid = await locked;
+    const delivery = keySend(f, key.token, { ...input, idempotencyKey: "key-after-wait" });
+    try {
+      await vi.waitFor(async () => {
+        const [row] = await server.db.execute(sql<{ blocked: boolean }>`select exists(select 1 from pg_stat_activity
+          where datname=current_database() and ${pid}=any(pg_blocking_pids(pid))) as blocked`);
+        expect(row.blocked).toBe(true);
+      }, { timeout: 5_000, interval: 10 });
+      await server.db.update(agentApiKeys).set(kind === "revoked" ? { revokedAt: new Date() }
+        : kind === "narrowed" ? { scopeConfig: { kind: "skill_test", issueId: f.issueId } }
+        : { responsibleUserId: randomUUID() }).where(eq(agentApiKeys.id, key.id));
+      unlock(); await gate;
+      expect((await delivery).status).toBe(403);
+      expect((await f.snapshot()).comments).toHaveLength(1);
+    } finally { unlock(); await gate; await delivery; }
+  }, 30_000);
+
+  it("publishes through the native tool without generic API tools, without starting a turn or changing the source", async () => {
+    const f = await fixture();
+    expect(f.authority.definitions().map(d => d.name)).toContain("send_chat_message");
+    const before = await issueService(server.db).getById(f.issueId);
+    const receipt = await f.authority.execute({ tool: "send_chat_message", arguments: input, callId: randomUUID() }) as { commentId: string; conversationId: string; chatUrl: string };
+    const snapshot = await f.snapshot();
+    const comment = snapshot.comments.find(c => c.id === receipt.commentId)!;
+    expect(comment).toMatchObject({ body: input.body, authorAgentId: f.agentId, createdByRunId: f.runId, onBehalfOfUserId: f.responsibleUserId,
+      metadata: { chatMessage: { sourceTaskId: f.issueId, sourceRunId: f.runId } } });
+    expect(snapshot.issues.find(i => i.id === receipt.conversationId)).toMatchObject({ conversationAgentId: f.agentId,
+      conversationUserId: f.responsibleUserId, conversationState: "waiting", executionRunId: null, status: "in_review" });
+    expect(await issueService(server.db).getById(f.issueId)).toEqual(before);
+    expect(await server.db.select().from(heartbeatRuns).where(eq(heartbeatRuns.companyId, f.companyId))).toHaveLength(1);
+    expect(snapshot.activity.filter(a => a.action === "issue.comment_added")).toHaveLength(1);
+    expect(await activityService(server.db).runsForIssue(f.companyId, receipt.conversationId)).toEqual([]);
+    expect(receipt.chatUrl).toContain(`/chats/${f.agentId}`);
+    expect(await withConversationReadState(server.db, f.companyId, f.responsibleUserId!, [{ id: receipt.conversationId }])).toMatchObject([{ isUnreadForMe: true }]);
+    expect(await f.authority.recover({ tool: "send_chat_message", arguments: input, callId: randomUUID() }))
+      .toMatchObject({ result: { commentId: receipt.commentId, replayed: true } });
+  });
+
+  it("creates once under concurrent first sends and recovers a committed response across run retries", async () => {
+    const f = await fixture();
+    expect(await f.authority.recover({ tool: "send_chat_message", arguments: input, callId: randomUUID() })).toBeNull();
+    expect((await f.snapshot()).issues.filter(i => i.conversationAgentId)).toHaveLength(0);
+    const [a, b] = await Promise.all([send(f), send(f)]);
+    expect(a!.commentId).toBe(b!.commentId);
+    expect((await f.snapshot()).comments).toHaveLength(1);
+    const other = await send(f, { ...input, idempotencyKey: "second" });
+    expect(other!.commentId).not.toBe(a!.commentId);
+    await expect(send(f, { ...input, body: "Different digest" })).rejects.toThrow(/different content/);
+    const nextRunId = randomUUID();
+    await server.db.update(heartbeatRuns).set({ status: "succeeded" }).where(eq(heartbeatRuns.id, f.runId));
+    await server.db.insert(heartbeatRuns).values({ id: nextRunId, companyId: f.companyId, agentId: f.agentId,
+      status: "running", nativeIssueId: f.issueId, responsibleUserId: f.responsibleUserId });
+    await server.db.update(issues).set({ executionRunId: nextRunId }).where(eq(issues.id, f.issueId));
+    expect(await send({ ...f, runId: nextRunId })).toMatchObject({ commentId: a!.commentId, replayed: true });
+    expect((await f.snapshot()).comments).toHaveLength(2);
+  });
+
+  it("supports HTTP routine delivery during an active chat reply and after a context reset", async () => {
+    const f = await fixture();
+    await server.db.update(heartbeatRuns).set({ invocationSource: "automation", triggerDetail: "routine" }).where(eq(heartbeatRuns.id, f.runId));
+    const first = await httpSend(f);
+    expect(first.status, await first.clone().text()).toBe(201);
+    const receipt = await first.json();
+    const replyRun = randomUUID();
+    await server.db.insert(heartbeatRuns).values({ id: replyRun, companyId: f.companyId, agentId: f.agentId, status: "running",
+      nativeIssueId: receipt.conversationId, responsibleUserId: f.responsibleUserId, contextSnapshot: { issueId: receipt.conversationId, conversationSessionGeneration: 0 } });
+    await server.db.update(issues).set({ executionRunId: replyRun, conversationState: "active" }).where(eq(issues.id, receipt.conversationId));
+    const before = await issueService(server.db).getById(receipt.conversationId);
+    expect((await httpSend(f, { ...input, idempotencyKey: "during-reply" })).status).toBe(201);
+    const after = await issueService(server.db).getById(receipt.conversationId);
+    expect(after).toMatchObject({ executionRunId: replyRun, conversationState: before!.conversationState, status: before!.status });
+    await server.db.update(issues).set({ conversationSessionGeneration: 1, conversationState: "waiting", executionRunId: null }).where(eq(issues.id, receipt.conversationId));
+    expect((await httpSend(f, { ...input, idempotencyKey: "after-new" })).status).toBe(201);
+    await expect(issueService(server.db).addComment(receipt.conversationId, "Stale reply", { agentId: f.agentId, runId: replyRun })).rejects.toThrow(/earlier session/);
+    expect(await server.db.select().from(heartbeatRuns).where(eq(heartbeatRuns.companyId, f.companyId))).toHaveLength(2);
+    expect((await f.snapshot()).comments).toHaveLength(3);
+  });
+
+  it("never enqueues a digest during recovery or the next human reply", async () => {
+    const f = await fixture(), svc = issueService(server.db);
+    const receipt = (await send(f))!;
+    const conversation = (await svc.getById(receipt.conversationId))!;
+    const enqueue = vi.fn(async (_agentId: string, _options: unknown) => null);
+    expect(await undeliveredConversationComments(server.db, f.companyId, conversation.id)).toEqual([]);
+    await deliverConversationComments(server.db, conversation, enqueue);
+    expect(enqueue).not.toHaveBeenCalled();
+    const reply = await svc.addComment(conversation.id, "Which PR should I review first?", { userId: f.responsibleUserId! }, { clientRequestId: randomUUID() });
+    expect((await undeliveredConversationComments(server.db, f.companyId, conversation.id)).map(comment => comment.id)).toEqual([reply.id]);
+    await deliverConversationComments(server.db, conversation, enqueue);
+    expect(enqueue).toHaveBeenCalledOnce();
+    expect(enqueue.mock.calls[0]?.[1]).toMatchObject({ requestedByActorType: "user", requestedByActorId: f.responsibleUserId,
+      contextSnapshot: { wakeCommentId: reply.id, wakeCommentIds: [reply.id] } });
+    expect(await conversationReplay(server.db, f.companyId, conversation.id, reply.id))
+      .toContain(JSON.stringify({ author: "agent", body: input.body }));
+  });
+
+  it.each([
+    { transport: "native", replay: false }, { transport: "native", replay: true },
+    { transport: "http", replay: false }, { transport: "http", replay: true },
+  ])("serializes $transport delivery with a native chat mutation, replay=$replay", async ({ transport, replay }) => {
+    const f = await fixture(), receipt = (await send(f))!, chatRunId = randomUUID();
+    await server.db.update(agents).set({ runtimeConfig: { heartbeat: { enabled: false, wakeOnDemand: false, maxConcurrentRuns: 2 } } }).where(eq(agents.id, f.agentId));
+    await server.db.insert(heartbeatRuns).values({ id: chatRunId, companyId: f.companyId, agentId: f.agentId, status: "running",
+      runtimeMode: "native", nativeIssueId: receipt.conversationId, responsibleUserId: f.responsibleUserId,
+      contextSnapshot: { issueId: receipt.conversationId, conversationSessionGeneration: 0 } });
+    await server.db.update(issues).set({ executionRunId: chatRunId, conversationState: "active" }).where(eq(issues.id, receipt.conversationId));
+    const chat = new PaperclipRunnerToolAuthority(server.db, { companyId: f.companyId, agentId: f.agentId,
+      issueId: receipt.conversationId, runId: chatRunId, apiUrl: server.apiUrl, apiToolsEnabled: false });
+    let unlock!: () => void, ready!: (pid: number) => void;
+    const locked = new Promise<number>(resolve => { ready = resolve; });
+    const release = new Promise<void>(resolve => { unlock = resolve; });
+    const gate = server.db.transaction(async tx => {
+      const [{ pid }] = await tx.execute(sql<{ pid: number }>`select pg_backend_pid() as pid`);
+      await tx.select({ id: agents.id }).from(agents).where(eq(agents.id, f.agentId)).for("update");
+      ready(pid);
+      await release;
+    });
+    const pid = await locked;
+    const waitForBlocked = async (count: number) => vi.waitFor(async () => {
+      const [row] = await server.db.execute(sql<{ count: number }>`with recursive blocked(pid) as (
+        select pid from pg_stat_activity where datname = current_database() and ${pid} = any(pg_blocking_pids(pid))
+        union select activity.pid from pg_stat_activity activity join blocked on blocked.pid = any(pg_blocking_pids(activity.pid))
+        where activity.datname = current_database()
+      ) select count(*)::int as count from blocked`);
+      expect(row.count).toBeGreaterThanOrEqual(count);
+    }, { timeout: 5000, interval: 10 });
+    const message = replay ? input : { ...input, idempotencyKey: "concurrent-message" };
+    let settled: Promise<PromiseSettledResult<unknown>[]> | undefined;
+    let observedDelivery: Promise<PromiseSettledResult<unknown>[]> | undefined;
+    try {
+      const delivery = transport === "native"
+        ? f.authority.execute({ tool: "send_chat_message", arguments: message, callId: randomUUID() })
+        : httpSend(f, message).then(async response => {
+          expect(response.status, await response.clone().text()).toBe(replay ? 200 : 201);
+          return response.json();
+        });
+      observedDelivery = Promise.allSettled([delivery]);
+      await waitForBlocked(1);
+      const mutation = chat.execute({ tool: "write_document", callId: randomUUID(), arguments: {
+        key: "concurrent-note", title: "Concurrent note", body: "The chat reply stays independent.", baseRevisionId: null, idempotencyKey: "concurrent-note",
+      } });
+      settled = Promise.allSettled([delivery, mutation]);
+      await waitForBlocked(2);
+      unlock();
+      await gate;
+      const results = await settled;
+      expect(results.map(result => result.status), JSON.stringify(results)).toEqual(["fulfilled", "fulfilled"]);
+      expect(results[1]).toMatchObject({ status: "fulfilled", value: { disposition: "applied", document: { key: "concurrent-note" } } });
+      expect(await issueService(server.db).getById(receipt.conversationId)).toMatchObject({ conversationState: "active" });
+    } finally {
+      unlock();
+      await gate;
+      await settled;
+      await observedDelivery;
+    }
+  }, 30_000);
+
+  it("isolates two humans sharing an agent and two agents serving one human", async () => {
+    const f = await fixture();
+    const a = await send(f);
+    const userId = randomUUID();
+    await server.db.insert(authUsers).values({ id: userId, name: "Second human", email: `${userId}@fixture.invalid`, emailVerified: true, createdAt: new Date(), updatedAt: new Date() });
+    await server.db.insert(companyMemberships).values({ companyId: f.companyId, principalType: "user", principalId: userId, status: "active", membershipRole: "member" });
+    await server.db.update(heartbeatRuns).set({ responsibleUserId: userId }).where(eq(heartbeatRuns.id, f.runId));
+    const b = await send(f);
+    expect(b!.conversationId).not.toBe(a!.conversationId);
+    const [agent] = await server.db.insert(agents).values({ companyId: f.companyId, name: "Second agent", status: "active", adapterType: "process" }).returning();
+    const runId = randomUUID();
+    await server.db.insert(heartbeatRuns).values({ id: runId, companyId: f.companyId, agentId: agent.id, status: "running", issueId: f.issueId, responsibleUserId: userId });
+    await server.db.update(issues).set({ assigneeAgentId: agent.id, executionRunId: runId }).where(eq(issues.id, f.issueId));
+    const c = await send({ ...f, agentId: agent.id, runId });
+    expect(new Set([a!.conversationId, b!.conversationId, c!.conversationId]).size).toBe(3);
+    await expect(issueService(server.db).addComment(a!.conversationId, "Wrong agent", { agentId: agent.id, runId })).rejects.toThrow(/Only this conversation/);
+    await expect(issueService(server.db).addComment(b!.conversationId, "Bypass", { agentId: f.agentId, runId: f.runId })).rejects.toThrow(/earlier session/);
+  });
+
+  it("delivers to its own chat while preserving pending questions and the original handoff completion", async () => {
+    const f = await fixture(), svc = issueService(server.db);
+    const own = await svc.create(f.companyId, { title: "Own chat", assigneeAgentId: f.agentId,
+      conversationAgentId: f.agentId, conversationUserId: f.responsibleUserId!, conversationState: "waiting", status: "in_review" });
+    const [coordinator] = await server.db.insert(agents).values({ companyId: f.companyId, name: "Coordinator", status: "active", adapterType: "process" }).returning();
+    const origin = await svc.create(f.companyId, { title: "Origin chat", assigneeAgentId: coordinator.id,
+      conversationAgentId: coordinator.id, conversationUserId: f.responsibleUserId!, conversationState: "waiting", status: "in_review" });
+    await recordAcceptedChatHandoff(server.db, (await svc.getById(f.issueId))!, origin);
+    const [question] = await server.db.insert(issueThreadInteractions).values({ companyId: f.companyId, issueId: own.id,
+      kind: "request_confirmation", status: "pending", payload: { version: 1, prompt: "Proceed?" } }).returning();
+    expect(await send(f)).toMatchObject({ conversationId: own.id });
+    expect(await server.db.select().from(issueComments).where(eq(issueComments.issueId, origin.id))).toEqual([]);
+    expect(await server.db.select().from(issueThreadInteractions).where(eq(issueThreadInteractions.id, question.id))).toEqual([question]);
+    expect(await server.db.select().from(heartbeatRuns).where(eq(heartbeatRuns.companyId, f.companyId))).toHaveLength(1);
+    await svc.update(f.issueId, { status: "done" });
+    expect(await server.db.select().from(chatCompletionDeliveries).where(eq(chatCompletionDeliveries.taskId, f.issueId)))
+      .toMatchObject([{ status: "pending", responseCommentId: null }]);
+    expect(await server.db.select().from(chatTaskHandoffs).where(eq(chatTaskHandoffs.taskId, f.issueId)))
+      .toMatchObject([{ conversationId: origin.id, agentId: coordinator.id }]);
+  });
+
+  it.each(["ask", "planning", "review", "watchdog", "stopped", "stale", "missing-human", "revoked", "private-task", "private-project", "private-ancestor", "paused-agent"])("rejects %s before creating a chat", async kind => {
+    const f = await fixture();
+    if (kind === "ask" || kind === "planning") await server.db.update(issues).set({ workMode: kind }).where(eq(issues.id, f.issueId));
+    if (kind === "review") await server.db.update(heartbeatRuns).set({ contextSnapshot: { issueId: f.issueId, nativeReviewInteractionId: randomUUID(), nativeReviewDecisionId: randomUUID() } }).where(eq(heartbeatRuns.id, f.runId));
+    if (kind === "watchdog") await server.db.update(heartbeatRuns).set({ contextSnapshot: { issueId: f.issueId, taskWatchdog: true, watchedIssueId: f.issueId } }).where(eq(heartbeatRuns.id, f.runId));
+    if (kind === "stopped") await server.db.update(heartbeatRuns).set({ resultJson: { executionCancellation: { state: "requested" } } }).where(eq(heartbeatRuns.id, f.runId));
+    if (kind === "stale") await server.db.update(issues).set({ executionRunId: null }).where(eq(issues.id, f.issueId));
+    if (kind === "missing-human") await server.db.update(heartbeatRuns).set({ responsibleUserId: null }).where(eq(heartbeatRuns.id, f.runId));
+    if (kind === "revoked") await server.db.delete(companyMemberships).where(eq(companyMemberships.principalId, f.responsibleUserId!));
+    if (kind === "private-task") await server.db.update(issues).set({ visibility: "private" }).where(eq(issues.id, f.issueId));
+    if (kind === "private-project") await server.db.update(projects).set({ visibility: "private", privacyOwnerUserId: f.responsibleUserId }).where(eq(projects.id, f.projectId));
+    if (kind === "private-ancestor") {
+      await server.db.update(issues).set({ visibility: "private" }).where(eq(issues.id, f.blockerId));
+      await server.db.update(issues).set({ parentId: f.blockerId, privacyParentIssueId: f.blockerId, privacyRootIssueId: f.blockerId }).where(eq(issues.id, f.issueId));
+    }
+    if (kind === "paused-agent") await server.db.update(agents).set({ status: "paused" }).where(eq(agents.id, f.agentId));
+    await expect(send(f)).rejects.toThrow();
+    expect((await f.snapshot()).comments).toHaveLength(0);
+    expect((await f.snapshot()).issues.filter(i => i.conversationAgentId)).toHaveLength(0);
+  });
+
+  it("rejects forged destinations and server-owned provenance, and respects the feature gate", async () => {
+    const f = await fixture();
+    expect((await httpSend(f, { ...input, agentId: f.agentId })).status).toBe(400);
+    await instanceSettingsService(server.db).updateExperimental({ enableAgentChat: false });
+    try { expect((await httpSend(f)).status).toBe(404); }
+    finally { await instanceSettingsService(server.db).updateExperimental({ enableAgentChat: true }); }
+    const receipt = await send(f);
+    const [comment] = await server.db.select().from(issueComments).where(eq(issueComments.id, receipt!.commentId));
+    await expect(issueService(server.db).addComment(f.issueId, "Forged source", { agentId: f.agentId, runId: f.runId }, { metadata: comment.metadata! })).rejects.toThrow(/server-owned/);
+  });
+
+  it("keeps unseen concurrent arrivals unread with exact comment cutoffs and monotonic receipts", async () => {
+    const f = await fixture();
+    const a = (await send(f))!, b = (await send(f, { ...input, idempotencyKey: "later" }))!;
+    await server.db.update(issueComments).set({ createdAt: sql`'2026-10-30 12:00:00.123456+00'::timestamptz` }).where(eq(issueComments.id, a.commentId));
+    await server.db.update(issueComments).set({ createdAt: sql`'2026-10-30 12:00:00.123789+00'::timestamptz` }).where(eq(issueComments.id, b.commentId));
+    const cookie = await server.humanSession(f.responsibleUserId!);
+    const mark = (id: string) => fetch(`${server.apiUrl}/api/issues/${a.conversationId}/read`, { method: "POST", headers: { Cookie: cookie, Origin: server.apiUrl, "Content-Type": "application/json" }, body: JSON.stringify({ throughCommentId: id }) });
+    const unread = async () => (await withConversationReadState(server.db, f.companyId, f.responsibleUserId!, [{ id: a.conversationId }]))[0].isUnreadForMe;
+    const response = await mark(a.commentId);
+    expect(response.status, await response.text()).toBe(200);
+    expect(await unread()).toBe(true);
+    expect((await mark(b.commentId)).status).toBe(200);
+    expect(await unread()).toBe(false);
+    await mark(a.commentId);
+    expect(await unread()).toBe(false);
+    const foreign = await server.fixture({ connectionScenario: "fresh" });
+    const foreignMessage = (await send(foreign))!;
+    expect((await mark(foreignMessage.commentId)).status).toBe(404);
+    const chats = await fetch(`${server.apiUrl}/api/companies/${f.companyId}/chats`, { headers: { Cookie: cookie } });
+    expect(chats.status).toBe(200);
+    expect(await chats.json()).toMatchObject([{ id: a.conversationId, isUnreadForMe: false }]);
+  });
+});

server/src/__tests__/agent-conversations.test.ts

@@ -29,9 +29,9 @@ import {
   issues,
 } from "@paperclipai/db";
 import {
-  getEmbeddedPostgresTestSupport,
-  startEmbeddedPostgresTestDatabase,
-} from "./helpers/embedded-postgres.js";
+  recoveryPostgresSupport as support,
+  startRecoveryPostgres,
+} from "./helpers/recovery-postgres.js";
 import { issueService } from "../services/issues.js";
 import { documentService } from "../services/documents.js";
 import { getTaskPlanContext } from "../services/task-plan-context.js";
@@ -58,16 +58,15 @@ import {
   heartbeatService,
 } from "../services/heartbeat.js";
 
-const support = await getEmbeddedPostgresTestSupport();
 (support.supported ? describe : describe.skip)(
   "persistent agent conversations",
   () => {
-    let database: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
+    let database: Awaited<ReturnType<typeof startRecoveryPostgres>>;
     let db: ReturnType<typeof createDb>;
     let companyId: string;
     let agentId: string;
     beforeAll(async () => {
-      database = await startEmbeddedPostgresTestDatabase(
+      database = await startRecoveryPostgres(
         "paperclip-agent-conversations-",
       );
       db = createDb(database.connectionString);

server/src/__tests__/chat-channels.integration.test.ts

@@ -61038,7 +61038,8 @@ describeEmbeddedPostgres("chat channel control-plane integration", () => {
         const beforeComments = await db
           .select({ id: issueComments.id })
           .from(issueComments)
-          .where(eq(issueComments.issueId, conversation.issueId));
+          .where(eq(issueComments.issueId, conversation.issueId))
+          .orderBy(issueComments.id);
         const beforeWakes = wakeup.mock.calls.length;
         const providerRuntime = runtime.endpoints.get(endpoint.id)!;
         const beforeProvider = {
@@ -61195,7 +61196,8 @@ describeEmbeddedPostgres("chat channel control-plane integration", () => {
           db
             .select({ id: issueComments.id })
             .from(issueComments)
-            .where(eq(issueComments.issueId, conversation.issueId)),
+            .where(eq(issueComments.issueId, conversation.issueId))
+            .orderBy(issueComments.id),
         ).resolves.toEqual(beforeComments);
         expect(wakeup.mock.calls.length).toBe(beforeWakes);
         expect({

server/src/__tests__/chat-completion-delivery.test.ts

@@ -5,7 +5,7 @@ import { and, asc, eq } from "drizzle-orm";
 import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { agents, agentWakeupRequests, chatCompletionDeliveries as deliveries, chatTaskHandoffs as handoffs,
   companies, createDb, documents, environmentLeases, heartbeatRuns, issueComments, issueRecoveryActions, issueThreadInteractions, issues } from "@paperclipai/db";
-import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
+import { recoveryPostgresSupport as support, startRecoveryPostgres } from "./helpers/recovery-postgres.js";
 import { settleInterruptedNativeBootstrap, terminalizeLegacyExecution } from "../services/legacy-execution-recovery.js";
 import { getExecutionBlocker } from "../services/execution-blocker.js";
 import { settleUnrecoverableExecutions } from "../services/execution-recovery-resolution.js";
@@ -16,12 +16,11 @@ import { instanceSettingsService } from "../services/instance-settings.js";
 import { chatCompletionDeliveryService, isCompletedOnboardingHandoffWake, prepareChatCompletionTurn, recordChatCompletion, recordChatHandoff } from "../services/chat-completion-delivery.js";
 import { heartbeatService, shouldQueueFollowupForRunningIssueWake } from "../services/heartbeat.js";
 
-const support = await getEmbeddedPostgresTestSupport();
 (support.supported ? describe : describe.skip)("chat completion delivery", () => {
   let db: ReturnType<typeof createDb>;
-  let temporary: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
+  let temporary: Awaited<ReturnType<typeof startRecoveryPostgres>>;
   beforeAll(async () => {
-    temporary = await startEmbeddedPostgresTestDatabase("chat-completion-"); db = createDb(temporary.connectionString);
+    temporary = await startRecoveryPostgres("chat-completion-"); db = createDb(temporary.connectionString);
     await instanceSettingsService(db).updateExperimental({ enableAgentChat: true });
   }, 30_000);
   afterAll(async () => { await temporary?.cleanup(); });

server/src/__tests__/chat-project-tools.test.ts

@@ -11,9 +11,8 @@ import { issueService } from "../services/issues.js";
 import { documentService } from "../services/documents.js";
 import { activityService } from "../services/activity.js";
 import { instanceSettingsService } from "../services/instance-settings.js";
-import { getEmbeddedPostgresTestSupport } from "./helpers/embedded-postgres.js";
+import { recoveryPostgresSupport as support } from "./helpers/recovery-postgres.js";
 
-const support = await getEmbeddedPostgresTestSupport();
 (support.supported ? describe : describe.skip)("chat project tool handoff", () => {
   let server: Awaited<ReturnType<typeof startRunnerApiTestServer>>;
   const originalSecret = process.env.PAPERCLIP_AGENT_JWT_SECRET;

server/src/__tests__/openapi-routes.test.ts

@@ -23,6 +23,7 @@ const apiPrefixes: Record<string, string> = {
   "agents.ts": "/api",
   "agent-project-access.ts": "/api",
   "agent-commentary.ts": "/api",
+  "agent-chat-messages.ts": "/api",
   "agent-avatars.ts": "/api",
   "agent-profile-avatar.ts": "/api",
   "announcements.ts": "/api",

server/src/app.ts

@@ -127,6 +127,7 @@ import {
 import { smokeLabRoutes } from "./routes/smoke-lab.js";
 import { costRoutes } from "./routes/costs.js";
 import { agentCommentaryRoutes } from "./routes/agent-commentary.js";
+import { agentChatMessageRoutes } from "./routes/agent-chat-messages.js";
 import { activityRoutes } from "./routes/activity.js";
 import { dashboardRoutes } from "./routes/dashboard.js";
 import { attentionRoutes } from "./routes/attention.js";
@@ -672,6 +673,7 @@ export async function createApp(
   api.use(companySkillPolicyRoutes(db));
   api.use(inboxAgentPolicyRoutes(db));
   api.use(agentCommentaryRoutes(db));
+  api.use(agentChatMessageRoutes(db));
   api.use(builtInAgentRoutes(db));
   api.use(summarySlotRoutes(db));
   api.use(statusCardRoutes(db));

server/src/routes/agent-chat-messages.ts

@@ -0,0 +1,22 @@
+import { Router } from "express";
+import type { Db } from "@paperclipai/db";
+import { forbidden } from "../errors.js";
+import { sendAgentChatMessage } from "../services/agent-chat-messages.js";
+import { assertCompanyAccess } from "./authz.js";
+
+export function agentChatMessageRoutes(db: Db) {
+  const router = Router();
+  router.post("/agents/me/chat/messages", async (req, res) => {
+    if (req.actor.type !== "agent" || !req.actor.agentId || !req.actor.companyId || !req.actor.runId) {
+      throw forbidden("An authenticated task run is required");
+    }
+    assertCompanyAccess(req, req.actor.companyId);
+    const receipt = await sendAgentChatMessage(db, {
+      companyId: req.actor.companyId, agentId: req.actor.agentId, runId: req.actor.runId, agentApiKeyId: req.actor.keyId,
+      keyScope: req.actor.keyScope, onBehalfOfUserId: req.actor.onBehalfOfUserId,
+      authorizingUserId: req.actor.authorizingUserId, source: req.actor.source,
+    }, req.body);
+    res.status(receipt!.replayed ? 200 : 201).json(receipt);
+  });
+  return router;
+}

server/src/routes/issues.ts

@@ -10,6 +10,8 @@ import { issueSummariesQuerySchema, type IssueSummary } from "@paperclipai/share
 import { listIssueSummaries } from "../services/issue-summaries.js";
 import { assertNoCaseHandoffMutation } from "../services/heartbeat/case-handoff-lifecycle.js";
 import { assertLegacyRunTaskOwnership } from "../legacy-run-task-ownership.js";
+import { withConversationReadState } from "../services/agent-chat-read-state.js";
+import { markIssueReadSchema } from "@paperclipai/shared";
 import { enqueueFastResponse } from "../services/fast-responses.js";
 import { hasRequiredWorkspaceRecovery, LEGACY_WORKSPACE_RECOVERY_SCHEMA } from "../services/workspace-restore-recovery-state.js";
 import { hasUnverifiedNativeWorkspaceFinalizationOwner } from "../services/native-runtime/native-workspace-finalization-recovery-state.js";
@@ -12106,11 +12108,22 @@ export function issueRoutes(
       res.status(403).json({ error: "Board user context required" });
       return;
     }
+    const input = markIssueReadSchema.parse(req.body ?? {});
+    let readAt: Date | SQL = new Date();
+    if (input.throughCommentId) {
+      if (!issue.conversationAgentId || issue.conversationUserId !== req.actor.userId) throw forbidden("Only the chat owner can mark a conversation message read");
+      const [comment] = await db.select({ createdAt: sql<string>`${issueComments.createdAt}::text` }).from(issueComments).where(and(
+        eq(issueComments.id, input.throughCommentId), eq(issueComments.companyId, issue.companyId), eq(issueComments.issueId, issue.id),
+        isNull(issueComments.deletedAt),
+      ));
+      if (!comment) throw notFound("Chat message not found");
+      readAt = sql`${comment.createdAt}::timestamptz`;
+    }
     const readState = await svc.markRead(
       issue.companyId,
       issue.id,
       req.actor.userId,
-      new Date(),
+      readAt,
     );
     const actor = getActorInfo(req);
     await logActivity(db, {
@@ -18544,7 +18557,7 @@ export function issueRoutes(
     if (req.actor.type !== "board" || !req.actor.userId) throw forbidden("Board user access required");
     if (!(await instanceSettings.getExperimental()).enableAgentChat) throw notFound("Agent Chat is disabled");
     const conversations = await svc.listConversations(companyId, req.actor.userId);
-    res.json(await filterIssuesForActor(req, conversations));
+    res.json(await withConversationReadState(db, companyId, req.actor.userId, await filterIssuesForActor(req, conversations)));
   });
 
   // GET stays read-only. POST resolves the single chat on explicit add or first send/upload.
@@ -18560,7 +18573,10 @@ export function issueRoutes(
       const agent = resolved.agent;
       const existing = await svc.getConversation(companyId, agent.id, req.actor.userId);
       if (existing && !(await assertIssueReadAllowed(req, res, existing))) return;
-      if (existing || method === "get") { res.json(existing); return; }
+      if (existing || method === "get") {
+        res.json(existing ? (await withConversationReadState(db, companyId, req.actor.userId, [existing]))[0] : null);
+        return;
+      }
       const issue = await svc.create(companyId, {
         title: `Chat with ${agent.name}`, assigneeAgentId: agent.id,
         conversationAgentId: agent.id, conversationUserId: req.actor.userId,
@@ -18569,7 +18585,7 @@ export function issueRoutes(
       await logActivity(db, { companyId, actorType: "user", actorId: req.actor.userId,
         action: "issue.conversation_opened", entityType: "issue", entityId: issue.id,
         details: { agentId: agent.id } });
-      res.json(issue);
+      res.json((await withConversationReadState(db, companyId, req.actor.userId, [issue]))[0]);
     });
   }
 

server/src/routes/openapi.ts

@@ -38,6 +38,8 @@ import {
   slackSearchConfigSchema,
   // Agent
   submitAgentCommentarySchema,
+  sendChatMessageSchema,
+  markIssueReadSchema,
   agentCommentaryQuerySchema,
   AGENT_PALETTE_IDS,
   AGENT_AVATAR_SIZES,
@@ -1670,6 +1672,7 @@ function resolveOperationAuthLevel(
       || /^\/api\/companies\/\{companyId\}\/agents\/\{agentId\}\/grok-binding(?:\/(?:routine|verify|retry|stop|recover))?$/.test(path)) return "board";
   if (PUBLIC_OPERATIONS.has(key)) return "public";
   if (key === "POST /api/companies/{companyId}/agent-commentary") return "agent_heartbeat";
+  if (key === "POST /api/agents/me/chat/messages") return "agent_heartbeat";
   if (method.toUpperCase() === "GET" && path.startsWith("/api/companies/{companyId}/agent-commentary")) return "board";
   if (key === "POST /api/mcp/project-tools" || key === "POST /api/companies/{companyId}/slack/tasks/{issueId}/tools") return "agent_run";
   if (RUNTIME_TOOLS_OPERATIONS.has(key)) return "runtime_tools";
@@ -4736,7 +4739,7 @@ registry.registerPath({
   path: "/api/issues/{id}/read",
   tags: ["issues"],
   summary: "Mark an issue as read",
-  request: { params: z.object({ id: z.string() }) },
+  request: { params: z.object({ id: z.string() }), body: { ...jsonBody(markIssueReadSchema), required: false } },
   responses: { 200: r.ok(), 401: r.unauthorized },
 });
 
@@ -5760,6 +5763,15 @@ registry.registerPath({
   responses: { 200: r.ok(), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },
 });
 
+registry.registerPath({
+  method: "post", path: "/api/agents/me/chat/messages", tags: ["agents"],
+  summary: "Send a task message to the agent's own chat",
+  description: "Requires the assigned agent's active standard task run, standard credentials and an active responsible human. Resolves or creates that agent's conversation automatically. Company visibility, task permissions, Stop and the shared cross-issue run cap apply. Equivalent retries do not spend another slot. Does not wake the chat agent or change task status.",
+  request: { body: jsonBody(sendChatMessageSchema) },
+  responses: { 200: r.ok(), 201: { ...r.ok(), description: "Message saved" }, 400: r.badRequest,
+    401: r.unauthorized, 403: r.forbidden, 404: r.notFound, 409: r.conflict, 429: r.tooManyRequests },
+});
+
 const agentCommentaryAcknowledgementSchema = z.object({
   id: z.string().uuid(),
   kind: z.enum(["complaint", "suggestion"]),

server/src/services/activity.ts

@@ -480,6 +480,10 @@ export function activityService(db: Db) {
         .where(
           and(
             eq(heartbeatRuns.companyId, companyId),
+            sql`(not exists (select 1 from ${issues} where ${issues.id} = ${issueId}
+              and ${issues.companyId} = ${companyId} and ${issues.conversationAgentId} is not null)
+              or coalesce(${heartbeatRuns.nativeIssueId}::text, ${heartbeatRuns.issueId}::text,
+                ${heartbeatRuns.contextSnapshot} ->> 'issueId', ${heartbeatRuns.contextSnapshot} ->> 'taskId') = ${issueId})`,
             ...(selectedRunIds ? [inArray(heartbeatRuns.id, selectedRunIds)] : []),
             or(
               eq(heartbeatRuns.issueId, issueId),

server/src/services/agent-chat-messages.ts

@@ -0,0 +1,193 @@
+import { createHash } from "node:crypto";
+import { and, eq, isNull, sql } from "drizzle-orm";
+import { agentApiKeys, agents, companies, companyMemberships, heartbeatRuns, issueComments, issues, nativeRunResults, type Db } from "@paperclipai/db";
+import { agentApiKeyScopeSchema, isUuidLike, sendChatMessageSchema, type AgentApiKeyScope } from "@paperclipai/shared";
+import { badRequest, conflict, forbidden, notFound, tooManyRequests } from "../errors.js";
+import { agentRunWritesRevoked, assertAgentRunWriteAllowed } from "../agent-run-cancellation.js";
+import { authorizationService, canActorReadIssuePrivacy, type AuthorizationActor } from "./authorization.js";
+import { persistActivity, publishActivity, type ActivityPublication } from "./activity-log.js";
+import { instanceSettingsService } from "./instance-settings.js";
+import { issueService } from "./issues.js";
+import { issueTreeControlService } from "./issue-tree-control.js";
+import { resolveActorSourceTrustForIssue } from "./source-trust.js";
+import { resolveTaskWatchdogMutationScope } from "./task-watchdog-scope.js";
+import { readNativeReviewAssignmentContext } from "./native-runtime/native-review-participant.js";
+import { nativeRunKeyScope } from "./native-runtime/native-skill-test-scope.js";
+import { crossIssueInfluenceLimitError, observeCrossIssueInfluence } from "./cross-issue-influence-limit.js";
+
+type Actor = { companyId: string; agentId: string; runId: string; agentApiKeyId?: string | null;
+  keyScope?: AgentApiKeyScope | null; onBehalfOfUserId?: string | null;
+  authorizingUserId?: string | null; source?: AuthorizationActor["source"] };
+export interface ChatMessageReceipt {
+  commentId: string;
+  conversationId: string;
+  chatUrl: string;
+  sourceTaskId: string;
+  replayed: boolean;
+}
+
+function runTask(run: typeof heartbeatRuns.$inferSelect) {
+  return run.nativeIssueId ?? run.issueId ?? run.contextSnapshot?.issueId ?? run.contextSnapshot?.taskId;
+}
+
+export async function sendAgentChatMessage(
+  db: Db,
+  actor: Actor,
+  value: unknown,
+  options: { authorizeNative?: (tx: Db) => Promise<unknown>; receiptOnly?: boolean } = {},
+): Promise<ChatMessageReceipt | null> {
+  const parsed = sendChatMessageSchema.safeParse(value);
+  if (!parsed.success) throw badRequest("Chat messages require body and idempotencyKey only", parsed.error.issues);
+  if (![actor.companyId, actor.agentId, actor.runId].every(isUuidLike)) throw forbidden("An authenticated task run is required");
+  const credentialScope = agentApiKeyScopeSchema.safeParse(actor.keyScope ?? { kind: "standard" });
+  if (!credentialScope.success) throw forbidden("The agent credential scope is invalid");
+  if (credentialScope.data.kind !== "standard") throw forbidden("Scoped test and task bridge credentials cannot publish agent chat messages");
+  const input = parsed.data;
+  const contentHash = createHash("sha256").update(input.body).digest("hex");
+  const publications: ActivityPublication[] = [];
+  const result = await db.transaction(async transaction => {
+    const tx = transaction as unknown as Db;
+    await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${`issue-privacy-tree:${actor.companyId}`}, 0))`);
+    const runWhere = and(eq(heartbeatRuns.id, actor.runId), eq(heartbeatRuns.companyId, actor.companyId), eq(heartbeatRuns.agentId, actor.agentId));
+    const [initial] = await tx.select().from(heartbeatRuns).where(runWhere);
+    const sourceId = initial && runTask(initial);
+    if (typeof sourceId !== "string" || !isUuidLike(sourceId)) throw forbidden("Chat delivery requires a task-bound run");
+    const sourceQuery = () => tx.select().from(issues).where(and(eq(issues.id, sourceId), eq(issues.companyId, actor.companyId)));
+    const [initialSource] = await sourceQuery();
+    if (!initialSource) throw forbidden("This run no longer owns the source task");
+    let source = initialSource;
+    const contextQuery = () => tx.select({ run: heartbeatRuns, agent: agents }).from(heartbeatRuns)
+      .innerJoin(agents, and(eq(agents.id, heartbeatRuns.agentId), eq(agents.companyId, heartbeatRuns.companyId)))
+      .where(runWhere);
+    const validateContext = (context: { run: typeof heartbeatRuns.$inferSelect; agent: typeof agents.$inferSelect } | undefined) => {
+      if (!context || context.run.status !== "running" || agentRunWritesRevoked(context.run)
+        || runTask(context.run) !== sourceId || source.assigneeAgentId !== actor.agentId
+        || source.executionRunId !== actor.runId || (source.checkoutRunId && source.checkoutRunId !== actor.runId)
+        || ["paused", "terminated", "pending_approval", "error"].includes(context.agent.status)) {
+        throw forbidden("This run no longer owns the source task");
+      }
+      if (source.conversationAgentId) throw forbidden("Reply normally in this conversation; send_chat_message is for execution tasks");
+      if (nativeRunKeyScope({ contextSnapshot: context.run.contextSnapshot, issueId: source.id, workMode: source.workMode }).kind === "skill_test") {
+        throw forbidden("Skill-test runs cannot publish agent chat messages");
+      }
+      if (source.workMode !== "standard" || ["done", "cancelled"].includes(source.status)
+        || readNativeReviewAssignmentContext(context.run.contextSnapshot)) {
+        throw forbidden("Chat delivery requires an ordinary task in standard execution mode");
+      }
+      return context;
+    };
+    const [initialContext] = await contextQuery();
+    const context = validateContext(initialContext);
+    if (!(await instanceSettingsService(tx).getExperimental()).enableAgentChat) throw notFound("Agent Chat is disabled");
+    const userId = context.run.responsibleUserId;
+    if (!userId) throw forbidden("This task has no responsible human to receive the message");
+    if (actor.onBehalfOfUserId !== undefined && actor.onBehalfOfUserId !== userId) throw forbidden("The authenticated responsible human no longer matches this run");
+    const assertCurrentKey = async (lock: boolean) => {
+      if (!actor.agentApiKeyId) return;
+      const query = tx.select().from(agentApiKeys).where(and(eq(agentApiKeys.id, actor.agentApiKeyId),
+        eq(agentApiKeys.companyId, actor.companyId), eq(agentApiKeys.agentId, actor.agentId), isNull(agentApiKeys.revokedAt)));
+      const [key] = lock ? await query.for("share") : await query;
+      const currentScope = key && agentApiKeyScopeSchema.safeParse(key.scopeConfig ?? { kind: "standard" });
+      if (!key || !currentScope?.success || JSON.stringify(currentScope.data) !== JSON.stringify(credentialScope.data)
+        || (key.responsibleUserId?.trim() || null) !== (actor.onBehalfOfUserId ?? userId)) {
+        throw forbidden("The agent key was revoked or its authority changed");
+      }
+    };
+    await assertCurrentKey(false);
+    const [membership] = await tx.select({ id: companyMemberships.id }).from(companyMemberships).where(and(
+      eq(companyMemberships.companyId, actor.companyId), eq(companyMemberships.principalType, "user"),
+      eq(companyMemberships.principalId, userId), eq(companyMemberships.status, "active"),
+    )).for("share");
+    if (!membership) throw forbidden("The responsible human is no longer an active company member");
+    const authActor: AuthorizationActor = { type: "agent", ...actor, keyId: actor.agentApiKeyId, keyScope: credentialScope.data,
+      source: actor.source ?? "agent_jwt", onBehalfOfUserId: actor.onBehalfOfUserId ?? userId };
+    const authorize = async (issueId: string, action: "issue:read" | "issue:comment") => {
+      const decision = await authorizationService(tx).decide({ actor: authActor, action,
+        resource: { type: "issue", companyId: actor.companyId, issueId } });
+      if (!decision.allowed) throw forbidden(decision.explanation);
+    };
+    await authorize(source.id, "issue:read");
+    if (!(await canActorReadIssuePrivacy(tx, { type: "none" }, source))) {
+      throw forbidden("Restricted task content cannot be sent to a company-visible chat");
+    }
+    const svc = issueService(tx);
+    let conversation = await svc.getConversation(actor.companyId, actor.agentId, userId);
+    if (!conversation && !options.receiptOnly) {
+      conversation = await svc.create(actor.companyId, {
+        title: `Chat with ${context.agent.name}`, assigneeAgentId: actor.agentId,
+        conversationAgentId: actor.agentId, conversationUserId: userId,
+        conversationState: "waiting", status: "in_review", createdByAgentId: actor.agentId,
+        responsibleUserId: userId, trustExplicitResponsibleUserId: true,
+      });
+      const opened = await persistActivity(tx, { companyId: actor.companyId, actorType: "agent", actorId: actor.agentId,
+        agentId: actor.agentId, runId: actor.runId, action: "issue.conversation_opened", entityType: "issue", entityId: conversation.id,
+        details: { agentId: actor.agentId, conversationUserId: userId } });
+      publications.push(opened.publication);
+    }
+    if (conversation) await tx.select({ id: issues.id }).from(issues).where(and(
+      eq(issues.id, conversation.id), eq(issues.companyId, actor.companyId),
+    )).for("update");
+    const [lockedSource] = await sourceQuery().for("update");
+    if (!lockedSource) throw forbidden("This run no longer owns the source task");
+    source = lockedSource;
+    if (options.authorizeNative) await options.authorizeNative(tx);
+    const [lockedContext] = await contextQuery().for("update");
+    const current = validateContext(lockedContext);
+    if (current.run.responsibleUserId !== userId) throw forbidden("The responsible human changed before this message was saved");
+    await assertCurrentKey(true);
+    if ((await resolveTaskWatchdogMutationScope(tx, { ...actor, type: "agent" })).kind !== "none") {
+      throw forbidden("Chat delivery requires an ordinary task in standard execution mode");
+    }
+    await assertAgentRunWriteAllowed(tx, actor.companyId, actor);
+    if (await issueTreeControlService(tx).getActivePauseHoldGate(actor.companyId, source.id)) throw forbidden("This task is paused");
+    const [finished] = await tx.select({ id: nativeRunResults.id }).from(nativeRunResults).where(and(
+      eq(nativeRunResults.companyId, actor.companyId), eq(nativeRunResults.runId, actor.runId), eq(nativeRunResults.schemaStatus, "accepted"),
+    )).limit(1);
+    if (finished) throw forbidden("Send the message before finishing the run");
+    if (!(await instanceSettingsService(tx).getExperimental()).enableAgentChat) throw notFound("Agent Chat is disabled");
+    await authorize(source.id, "issue:read");
+    if (!conversation) return null;
+    await authorize(conversation.id, "issue:comment");
+    const recipientDecision = await authorizationService(tx).decide({ actor: { type: "board", userId, source: "session", ignoreInstanceAdmin: true },
+      action: "issue:read", resource: { type: "issue", companyId: actor.companyId, issueId: conversation.id } });
+    if (!recipientDecision.allowed) throw forbidden("The responsible human cannot access this chat");
+    const requestId = `chat:${source.id}:${createHash("sha256").update(input.idempotencyKey).digest("hex")}`;
+    const [prior] = await tx.select().from(issueComments).where(and(eq(issueComments.companyId, actor.companyId),
+      eq(issueComments.issueId, conversation.id), eq(issueComments.authorAgentId, actor.agentId), eq(issueComments.clientRequestId, requestId)));
+    const [company] = await tx.select({ prefix: companies.issuePrefix }).from(companies).where(eq(companies.id, actor.companyId));
+    const receipt = (commentId: string, replayed: boolean): ChatMessageReceipt => ({ commentId, conversationId: conversation!.id,
+      chatUrl: `/${company.prefix}/chats/${actor.agentId}`, sourceTaskId: source.id, replayed });
+    if (prior) {
+      if (prior.metadata?.chatMessage?.contentHash !== contentHash) {
+        if (options.receiptOnly) return null;
+        throw conflict("Chat message retry key was already used with different content");
+      }
+      return receipt(prior.id, true);
+    }
+    if (options.receiptOnly) return null;
+    const influence = await observeCrossIssueInfluence(tx, { companyId: actor.companyId, agentId: actor.agentId,
+      runId: actor.runId, responsibleUserId: userId, targetIssueId: conversation.id,
+      targetIssueIdentifier: conversation.identifier, kind: "comment" });
+    if (influence && !influence.allowed) {
+      const denial = crossIssueInfluenceLimitError(influence, { actorLabel: current.agent.name,
+        assigneeLabel: current.agent.name, issueIdentifier: conversation.identifier });
+      throw tooManyRequests(denial.error, denial.details);
+    }
+    const sourceTrust = await resolveActorSourceTrustForIssue({ db: tx, issue: source,
+      actor: { actorType: "agent", actorId: actor.agentId, agentId: actor.agentId, runId: actor.runId } });
+    const comment = await svc.addComment(conversation.id, input.body, { agentId: actor.agentId, runId: actor.runId }, {
+      clientRequestId: requestId, sourceTrust, proactiveChatMessage: { sourceTaskId: source.id, userId },
+      metadata: { version: 1, chatMessage: { sourceTaskId: source.id, sourceTaskIdentifier: source.identifier!, sourceRunId: actor.runId, contentHash },
+        sections: [{ rows: [{ type: "issue_link", issueId: source.id, identifier: source.identifier, label: "Source task" }] }] },
+    }, tx);
+    const activity = await persistActivity(tx, { companyId: actor.companyId, actorType: "agent", actorId: actor.agentId,
+      agentId: actor.agentId, runId: actor.runId, agentApiKeyId: actor.agentApiKeyId,
+      action: "issue.comment_added", entityType: "issue", entityId: conversation.id,
+      details: { commentId: comment.id, identifier: conversation.identifier, conversationUserId: userId,
+        conversationAgentId: actor.agentId, sourceTaskId: source.id } });
+    publications.push(activity.publication);
+    return receipt(comment.id, false);
+  });
+  for (const publication of publications) publishActivity(publication);
+  return result;
+}

server/src/services/agent-chat-read-state.ts

@@ -0,0 +1,21 @@
+import { and, eq, inArray, sql } from "drizzle-orm";
+import { issueComments, issueReadStates, type Db } from "@paperclipai/db";
+
+export async function withConversationReadState<T extends { id: string }>(db: Db, companyId: string, userId: string, conversations: T[]) {
+  if (!conversations.length) return [] as Array<T & { isUnreadForMe: boolean; lastExternalCommentAt: Date | null }>;
+  const rows = await db.select({
+    issueId: issueComments.issueId,
+    latest: sql<Date>`max(${issueComments.createdAt})`,
+    unread: sql<boolean>`bool_or(${issueComments.createdAt} > coalesce(${issueReadStates.lastReadAt}, to_timestamp(0)))`,
+  }).from(issueComments).leftJoin(issueReadStates, and(
+    eq(issueReadStates.companyId, companyId), eq(issueReadStates.issueId, issueComments.issueId), eq(issueReadStates.userId, userId),
+  )).where(and(eq(issueComments.companyId, companyId), inArray(issueComments.issueId, conversations.map(chat => chat.id)),
+    sql`${issueComments.deletedAt} is null`, sql`${issueComments.authorAgentId} is not null`,
+    sql`${issueComments.authorType} is distinct from 'system'`,
+    sql`${issueComments.presentation} ->> 'kind' is distinct from 'system_notice'`,
+    eq(issueComments.origin, "comment"),
+  )).groupBy(issueComments.issueId);
+  const byId = new Map(rows.map(row => [row.issueId, row]));
+  return conversations.map(chat => ({ ...chat, isUnreadForMe: byId.get(chat.id)?.unread ?? false,
+    lastExternalCommentAt: byId.get(chat.id)?.latest ?? null }));
+}

server/src/services/agent-conversations.ts

@@ -526,6 +526,9 @@ export async function undeliveredConversationComments(
         eq(issueComments.companyId, companyId),
         eq(issueComments.issueId, issueId),
         isNull(issueComments.deletedAt),
+        sql`${issueComments.authorUserId} is not null`,
+        isNull(issueComments.authorAgentId),
+        eq(issueComments.origin, "comment"),
         sql`${issueComments.clientRequestId} is not null`,
         sql`not exists (select 1 from ${agentWakeupRequests} where ${agentWakeupRequests.companyId} = ${companyId}
       and ${agentWakeupRequests.idempotencyKey} = 'conversation-comment:' || ${issueComments.id}::text)`,

server/src/services/issues.ts

@@ -30,7 +30,7 @@ import { requestRestorePointDeletion } from "./git-restore-point-ledger.js";
 import { DELIVERY_QUEUES, notifyDeliveryWork } from "./delivery-work-notifications.js";
 import { recordChatHandoff, recordAcceptedChatHandoff, lockAcceptedChatHandoffSource, recordChatCompletion, existingChatCompletionReply, acknowledgeChatCompletionReply } from "./chat-completion-delivery.js";
 import { mirrorSlackBoardComment, slackBoardReplyBindings } from "./slack-board-messages.js";
-import { assertAgentRunWriteAllowed } from "../agent-run-cancellation.js";
+import { agentRunWritesRevoked, assertAgentRunWriteAllowed } from "../agent-run-cancellation.js";
 import { assertLegacyRunTaskOwnership } from "../legacy-run-task-ownership.js";
 import { retryIdempotentDatabaseOperation } from "../database-retry.js";
 import { externalConversationStateSql, nonIdleSlackIssueCondition, resumeSlackConversation } from "./slack-conversation-state.js";
@@ -143,7 +143,7 @@ import {
   isUuidLike,
   normalizeIssueIdentifier as normalizeIssueReferenceIdentifier,
 } from "@paperclipai/shared";
-import { conflict, HttpError, notFound, unprocessable } from "../errors.js";
+import { conflict, forbidden, HttpError, notFound, unprocessable } from "../errors.js";
 import { isForeignKeyViolation } from "../db-errors.js";
 import { logger } from "../middleware/logger.js";
 import { parseObject } from "../adapters/utils.js";
@@ -1685,6 +1685,7 @@ function withAgentCommentAuthorizationMetadata(
   const reason = authorizationReason?.trim() || "internal_agent_write";
   return {
     version: 1,
+    ...(metadata?.chatMessage ? { chatMessage: metadata.chatMessage } : {}),
     ...(metadata?.sourceRunId !== undefined
       ? { sourceRunId: metadata.sourceRunId }
       : {}),
@@ -8615,7 +8616,7 @@ export function issueService(db: Db) {
       companyId: string,
       issueId: string,
       userId: string,
-      readAt: Date = new Date(),
+      readAt: Date | SQL = new Date(),
     ) => {
       const now = new Date();
       const [row] = await db
@@ -8634,7 +8635,7 @@ export function issueService(db: Db) {
             issueReadStates.userId,
           ],
           set: {
-            lastReadAt: readAt,
+            lastReadAt: sql`greatest(${issueReadStates.lastReadAt}, excluded.last_read_at)`,
             updatedAt: now,
           },
         })
@@ -12827,6 +12828,7 @@ export function issueService(db: Db) {
         sourceTrust?: typeof issueComments.$inferInsert.sourceTrust;
         createdAt?: Date | string | null;
         clientRequestId?: string;
+        proactiveChatMessage?: { sourceTaskId: string; userId: string };
         /** Server-only: authenticated Paperclip messages also belong in the Slack thread. */
         mirrorToSlack?: boolean;
       },
@@ -12883,11 +12885,28 @@ export function issueService(db: Db) {
           return existing;
         }
       }
+      if (options?.metadata?.chatMessage && !options.proactiveChatMessage) {
+        throw forbidden("Chat message provenance is server-owned");
+      }
+      if (issue.conversationAgentId && actor.agentId && issue.conversationAgentId !== actor.agentId) {
+        throw forbidden("Only this conversation's agent can post agent messages");
+      }
+      if (issue.conversationAgentId && actor.agentId && !actor.runId) {
+        throw forbidden("Agent chat messages require an authenticated run");
+      }
       if (issue.conversationAgentId && actor.runId) {
         const [run] = await dbOrTx.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, actor.runId));
         const [current] = await dbOrTx.select().from(issues).where(eq(issues.id, issueId));
-        if (run?.status === "cancelled") throw conflict("This conversation turn was cancelled; it cannot post a reply");
-        if (run?.contextSnapshot?.conversationSessionGeneration !== current.conversationSessionGeneration) {
+        if (agentRunWritesRevoked(run)) throw conflict("This conversation turn was cancelled; it cannot post a reply");
+        const runTaskId = run?.nativeIssueId ?? run?.issueId ?? run?.contextSnapshot?.issueId ?? run?.contextSnapshot?.taskId;
+        if (options?.proactiveChatMessage) {
+          if (run?.status !== "running" || run.agentId !== actor.agentId || run.companyId !== issue.companyId
+            || runTaskId !== options.proactiveChatMessage.sourceTaskId || runTaskId === issueId
+            || current.conversationUserId !== options.proactiveChatMessage.userId
+            || run.responsibleUserId !== current.conversationUserId) {
+            throw forbidden("Invalid background chat message authority");
+          }
+        } else if (runTaskId !== issueId || run?.contextSnapshot?.conversationSessionGeneration !== current.conversationSessionGeneration) {
           throw conflict("Conversation session changed; this reply belongs to an earlier session");
         }
       }
@@ -13022,7 +13041,7 @@ export function issueService(db: Db) {
             : (options?.metadata ?? null),
         );
       let comment: typeof issueComments.$inferSelect | null = null;
-      if (createdByRunId) {
+      if (createdByRunId && !options?.proactiveChatMessage) {
         const existing = await dbOrTx
           .select()
           .from(issueComments)

server/src/services/native-runtime/paperclip-runner-tool-authority.test.ts

@@ -120,7 +120,7 @@ describe("PaperclipRunnerToolAuthority", () => {
       issueId,
       runId,
     });
-    expect(authority.definitions()).toHaveLength(50);
+    expect(authority.definitions()).toHaveLength(51);
     expect(authority.definitions().map(tool => tool.name)).toEqual(expect.arrayContaining([
       "get_workspace", "list_workspaces", "select_workspace", "prepare_repository",
     ]));

server/src/services/native-runtime/paperclip-runner-tool-authority.ts

@@ -26,6 +26,7 @@ import { createReadStream } from "node:fs";
 import { publicChatTaskUrl } from "../chat-task-url.js";
 import { agentCommentaryToolInputSchema } from "@paperclipai/shared";
 import { submitAgentCommentary } from "../agent-commentary.js";
+import { sendAgentChatMessage } from "../agent-chat-messages.js";
 import type { createAssignedMcpTools } from "./assigned-mcp-tools.js";
 import { captureRunnerToolResult, fitRunnerToolResultPage, READ_TOOL_RESULT, READ_TOOL_RESULT_DEFINITION, readToolResultSchema, RUNNER_TOOL_RESULT_MAX_BYTES } from "./runner-tool-results.js";
 import { assertAssignableAgent } from "../agent-assignability.js";
@@ -124,6 +125,7 @@ import {
 
 const EXTERNAL_WORKSPACE_OPERATIONS = new Set(["get_workspace", "list_workspaces", "select_workspace", "prepare_repository", "register_deliverable"]);
 const IMPLEMENTED_OPERATIONS = new Set([
+  "send_chat_message",
   "submit_complaint", "submit_suggestion",
   "read_agent_instructions", "update_agent_instructions", "get_agent_instruction_history", "restore_agent_instructions",
   "search_api", "call_api", "hire_agent",
@@ -432,6 +434,7 @@ export class PaperclipRunnerToolAuthority {
     // retry, without ever falling through to an uncertain mutation.
     let recovered: unknown;
     if (call.tool === "set_task_title") recovered = await this.#setTaskTitle(input, true);
+    else if (call.tool === "send_chat_message") recovered = await this.#sendChatMessage(input, this.#privacyActor(run), true);
     else if (call.tool === "submit_complaint" || call.tool === "submit_suggestion") recovered = await this.#submitCommentary(call.tool, input, true);
     else if (call.tool === "create_task") recovered = await this.#createTask(input, null, true);
     else if (call.tool === "request_human_input") recovered = await this.#requestHumanInput(input, null, true);
@@ -957,6 +960,7 @@ export class PaperclipRunnerToolAuthority {
         return { approval, tasks: tasks.filter(row => !readable || readable.has(row.issue.id)).map(row => row.issue) };
       }
       case "report_progress": return this.#reportProgress(input);
+      case "send_chat_message": return this.#sendChatMessage(input, this.#privacyActor(context.run));
       case "request_human_input": return this.#requestHumanInput(input,
         (await captureRunIdentity(this.db, this.binding, { readScope: "identity" })).context?.id ?? null);
       case "create_task": return this.#createTask(input,
@@ -1484,6 +1488,14 @@ export class PaperclipRunnerToolAuthority {
     return { interactionId: review.interaction.id, status: expectedStatus };
   }
 
+  async #sendChatMessage(input: Record<string, unknown>, actor: AuthorizationActor, receiptOnly = false) {
+    const result = await sendAgentChatMessage(this.db, { ...this.binding, keyScope: actor.keyScope,
+      onBehalfOfUserId: actor.onBehalfOfUserId, authorizingUserId: actor.authorizingUserId, source: actor.source }, input, {
+      authorizeNative: tx => this.#lockAuthorizedMutationContext(tx), receiptOnly,
+    });
+    return result ?? undefined;
+  }
+
   async #reportProgress(input: Record<string, unknown>): Promise<unknown> {
     const body = typeof input.body === "string" ? input.body.trim() : "";
     const idempotencyKey = typeof input.idempotencyKey === "string" ? input.idempotencyKey.trim() : "";

server/src/services/native-runtime/runner-api-catalog.ts

@@ -41,6 +41,7 @@ function words(text: string): string[] {
 }
 
 function dedicatedTools(method: string, path: string): string[] {
+  if (method === "POST" && path === "/api/agents/me/chat/messages") return ["send_chat_message"];
   if (/\/companies\/\{[^}]+\}\/workflows$/.test(path)) return method === "GET" ? ["list_workflows"] : method === "POST" ? ["create_workflow"] : [];
   if (/\/workflows\/\{[^}]+\}$/.test(path)) return method === "GET" ? ["read_workflow"] : method === "PATCH" ? ["update_workflow"] : [];
   if (/\/issues\/\{[^}]+\}\/title$/.test(path) && method === "PUT") return ["set_task_title"];

skills/paperclip/references/routines.md

@@ -229,3 +229,19 @@ GET /api/routines/{routineId}/runs?limit=50
 ```
 
 Use the generic API endpoint tables in `skills/paperclip/references/api-reference.md` when you need a full cross-domain reference. Use this file when you need routine-specific behaviour, payload shape, or policy details.
+
+**Delivering results to the human's chat**
+
+A routine execution task can call `send_chat_message({ body, idempotencyKey })`
+or `POST /api/agents/me/chat/messages` using its run credentials. The server sends
+to that agent's chat with the run's responsible human, including before the human
+has opened the chat. No recipient lookup or destination ID is needed. Retain a
+stable key across retries of the source task; changed content with that key conflicts.
+
+For a morning PR review, gather the PRs, send a concise Markdown digest with
+links, then finish the task separately. Delivery commits immediately, marks the
+chat unread and includes a source-task link. It neither wakes the chat agent nor
+suppresses ordinary handoff completion notifications. Agent Chat must be enabled,
+the run must be active in standard mode, and the source task must be suitable
+for the company-visible chat. Missing or revoked recipients and restricted tasks
+fail explicitly; never select a replacement recipient.

tests/e2e/agent-chat-messages.spec.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "@playwright/test";
+import { idle, json, send, setup } from "./agent-chat.shared";
+
+test.use({ trace: "retain-on-failure" });
+test.setTimeout(120_000);
+
+test("a routine delivers a first digest, unread state, source link and replyable history", async ({ page, request }) => {
+  const f = await setup(request);
+  try {
+    await page.goto(`/${f.company.issuePrefix}/chats/${f.agents[1].id}`);
+    await expect(page.getByTestId("task-chat-composer-input")).toBeVisible();
+    const routine = await json(await request.post(`/api/companies/${f.company.id}/routines`, { data: {
+      title: "Morning PR review", description: "proactive-digest-fixture", assigneeAgentId: f.agent.id,
+    } }));
+    await json(await request.post(`/api/routines/${routine.id}/run`, { data: { idempotencyKey: "browser-morning" } }));
+    await expect(page.getByRole("img", { name: "Unread messages from Alpha", exact: true })).toBeVisible({ timeout: 45_000 });
+    await expect(page.getByLabel(/unread chats/)).toBeVisible();
+    let chat: any;
+    await expect.poll(async () => {
+      chat = await json(await request.get(f.chatPath));
+      return chat?.isUnreadForMe;
+    }).toBe(true);
+    const comments = await json(await request.get(`/api/issues/${chat.id}/comments`));
+    const digest = comments.find((c: any) => c.metadata?.chatMessage);
+    expect(digest.authorAgentId).toBe(f.agent.id);
+    const sourceId = digest.metadata.chatMessage.sourceTaskId;
+    const source = await json(await request.get(`/api/issues/${sourceId}`));
+    expect(source.originKind).toBe("routine_execution");
+    expect(await json(await request.get(`/api/issues/${chat.id}/runs`))).toEqual([]);
+    await page.reload();
+    await expect(page.getByRole("img", { name: "Unread messages from Alpha", exact: true })).toBeVisible();
+    await page.goto(f.route);
+    await expect(page.getByText("Morning PR digest", { exact: true })).toBeVisible();
+    const sourceLink = page.getByRole("link", { name: `From ${source.identifier}`, exact: true });
+    await expect(sourceLink).toBeVisible();
+    await expect.poll(async () => (await json(await request.get(f.chatPath))).isUnreadForMe).toBe(false);
+    await sourceLink.click();
+    await expect(page).toHaveURL(new RegExp(`/issues/${source.identifier}`));
+    await page.goto(f.route);
+    await send(page, { action: "digest-followup", text: "Which was the first PR?" });
+    await idle(request, f.chatPath, 2);
+    await expect(page.getByText("The first PR in your morning digest is PR 123.", { exact: true })).toBeVisible({ timeout: 45_000 });
+  } finally { await f.restore(); }
+});

tests/e2e/agent-chat-sessions.spec.ts

@@ -264,7 +264,7 @@ test("secondary chat navigation preserves layout, unique conversations, history,
       data: { enableStreamlinedUi: true },
     }));
     await page.goto(`/${f.company.issuePrefix}/dashboard`);
-    await page.getByRole("link", { name: "Chat", exact: true }).click();
+    await page.getByRole("link", { name: /^Chat(?:\s|$)/ }).click();
     // With no recent conversation, Chat opens the first human-created primary.
     // Navigation alone must not create a conversation or start execution.
     expect(await json(await request.get(`/api/companies/${f.company.id}/primary-agent/me`))).toMatchObject({
@@ -333,7 +333,7 @@ test("secondary chat navigation preserves layout, unique conversations, history,
     await expect(editor).toContainText("Unsent draft for Alpha");
     await expect(nav.getByRole("link")).toHaveCount(6);
 
-    await page.getByRole("link", { name: "Chat", exact: true }).click();
+    await page.getByRole("link", { name: /^Chat(?:\s|$)/ }).click();
     await expect(page.getByRole("link", { name: "Configure Alpha", exact: true })).toBeVisible();
     await expect(editor).toContainText("Unsent draft for Alpha");
     expect(await sidebar.boundingBox()).toEqual(landingBounds);
@@ -346,7 +346,7 @@ test("secondary chat navigation preserves layout, unique conversations, history,
       },
     }));
     await idle(request, betaPath);
-    await page.getByRole("link", { name: "Chat", exact: true }).click();
+    await page.getByRole("link", { name: /^Chat(?:\s|$)/ }).click();
     await expect(page.getByRole("link", { name: "Configure Alpha", exact: true })).toBeVisible();
     await compose.click();
     await picker.getByRole("combobox").fill("Beta");

tests/e2e/fixtures/agent-chat.mjs

@@ -24,6 +24,14 @@ const task = await api(`/issues/${ctx.issueId}`);
 const comment = async (body) =>
   api(`/issues/${task.id}/comments`, "POST", { body });
 if (!task.conversationAgentId) {
+  if (task.description?.includes("proactive-digest-fixture")) {
+    await api("/agents/me/chat/messages", "POST", {
+      body: "## Morning PR digest\n\nPlease review [PR 123](https://github.com/paperclipai/paperclip/pull/123), [PR 456](https://github.com/paperclipai/paperclip/pull/456), and [PR 789](https://github.com/paperclipai/paperclip/pull/789).",
+      idempotencyKey: "morning-digest",
+    });
+    await api(`/issues/${task.id}`, "PATCH", { status: "done", comment: "Digest delivered." });
+    process.exit(0);
+  }
   const plan = await api(`/issues/${task.id}/documents/plan`);
   await api(`/issues/${task.id}/documents/output`, "PUT", {
     title: "Output",
@@ -178,6 +186,10 @@ if (command.action === "hold") {
     },
   });
   await comment("Please choose an audience.");
+} else if (command.action === "digest-followup") {
+  const digest = comments.find(c => c.metadata?.chatMessage && c.body.includes("Morning PR digest"));
+  if (!digest) throw new Error("Proactive digest is missing from the next human turn's history");
+  await comment("The first PR in your morning digest is PR 123.");
 } else if (command.action === "history") {
   for (let index = 0; index < 65; index++)
     await comment(`History message ${String(index).padStart(2, "0")}`);

ui/src/api/issues.ts

@@ -377,8 +377,8 @@ export const issuesApi = {
     api.put<IssueWatchdog>(`/issues/${id}/watchdog`, data),
   deleteWatchdog: (id: string) =>
     api.delete<{ ok: true }>(`/issues/${id}/watchdog`),
-  markRead: (id: string) =>
-    api.post<{ id: string; lastReadAt: Date }>(`/issues/${id}/read`, {}),
+  markRead: (id: string, throughCommentId?: string) =>
+    api.post<{ id: string; lastReadAt: Date }>(`/issues/${id}/read`, throughCommentId ? { throughCommentId } : {}),
   markUnread: (id: string) =>
     api.delete<{ id: string; removed: boolean }>(`/issues/${id}/read`),
   archiveFromInbox: (id: string) =>

ui/src/components/AgentConversationSidebar.tsx

@@ -15,6 +15,7 @@ export interface AgentConversationSidebarProps {
   availableAgents?: Agent[];
   activeId?: string;
   previews?: Record<string, string>;
+  unreadAgentIds?: readonly string[];
   loading?: boolean;
   error?: Error | null;
   onRetry?: () => void;
@@ -28,7 +29,7 @@ export interface AgentConversationSidebarProps {
 }
 
 /** Searchable navigation for one conversation per agent. */
-export function AgentConversationSidebar({ agents, existingChatAgentIds, availableAgents = agents, activeId, previews = {}, loading = false, error, onRetry, initialSearch = "", onSelect, onBrowse, onAddChat, historyLoading, historyError, onRetryHistory }: AgentConversationSidebarProps) {
+export function AgentConversationSidebar({ agents, existingChatAgentIds, availableAgents = agents, activeId, previews = {}, unreadAgentIds = [], loading = false, error, onRetry, initialSearch = "", onSelect, onBrowse, onAddChat, historyLoading, historyError, onRetryHistory }: AgentConversationSidebarProps) {
   const navigate = useNavigate();
   const [pickerOpen, setPickerOpen] = useState(false);
   const [search, setSearch] = useState(initialSearch);
@@ -82,6 +83,7 @@ export function AgentConversationSidebar({ agents, existingChatAgentIds, availab
             <span className="truncate text-sm font-medium">{agent.name}</span>
             <span className="truncate text-xs text-muted-foreground">{agent.status === "terminated" ? "Terminated" : agent.status === "paused" ? "Paused" : previews[agent.id] ?? agent.title ?? "Start a conversation"}</span>
           </span>
+          {unreadAgentIds.includes(agent.id) && <span role="img" aria-label={`Unread messages from ${agent.name}`} className="size-2 shrink-0 rounded-full bg-primary" />}
         </Link>)}
       </nav> : !agents.length && (historyLoading || historyError) ? null : <div className="flex flex-col items-start gap-2 px-2 py-6">
         <p className="text-sm font-medium">{agents.length ? "No agents found" : "No chats yet"}</p>

ui/src/components/AgentConversationsSidebar.test.tsx

@@ -90,6 +90,19 @@ it("preserves recent activity order when reopening an older conversation", async
   expect(links()).toEqual(["/chats/bob", "/chats/alice"]);
 });
 
+it("shows accessible unread indicators only for the current company and human", async () => {
+  client.setQueryData(queryKeys.agentChats.list("company-a", "user-a"), [{ ...chat("alice"), isUnreadForMe: true }, chat("bob")]);
+  client.setQueryData(queryKeys.agentChats.list("company-a", "other-human"), [{ ...chat("bob"), isUnreadForMe: true }]);
+  await render();
+  expect(container.querySelector('[aria-label="Unread messages from alice"]')).not.toBeNull();
+  expect(container.querySelector('[aria-label="Unread messages from bob"]')).toBeNull();
+  state.companyId = "company-b";
+  client.setQueryData(queryKeys.agents.list("company-b"), []);
+  client.setQueryData(queryKeys.agentChats.list("company-b", "user-a"), []);
+  await render();
+  expect(container.querySelector('[aria-label^="Unread messages"]')).toBeNull();
+});
+
 it("retains terminated agents' history by id without offering them for new chats", async () => {
   const retired = { ...roster[0], id: "retired-id", name: "Retired", status: "terminated", urlKey: "alice" };
   client.setQueryData(queryKeys.agents.detail(retired.id), retired);

ui/src/components/AgentConversationsSidebar.tsx

@@ -47,6 +47,7 @@ export function AgentConversationsSidebar() {
   return <AgentConversationSidebar key={`${companyId}:${userId}`} agents={[...conversations, ...teammates]} availableAgents={roster}
     existingChatAgentIds={conversations.map(agent => agent.id)}
     activeId={active?.id} previews={previews}
+    unreadAgentIds={(chats.data ?? []).filter(chat => chat.isUnreadForMe).flatMap(chat => chat.conversationAgentId ? [chat.conversationAgentId] : [])}
     // Loaded chats stay listed through an outage (the banner covers it); an
     // outage before the first load is a skeleton, and only a real failure is an error.
     loading={[agents, chats, session].some(query => { const kind = queryViewKind(query); return kind === "loading" || kind === "reconnecting"; })}

ui/src/components/CoordinatorSidebar.test.tsx

@@ -10,9 +10,9 @@ import { coordinatorAttentionQueryKey, coordinatorAttentionSummaryQueryKey } fro
 import { queryKeys } from "@/lib/queryKeys";
 
 (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
-const fixture = vi.hoisted(() => ({ attention: vi.fn(), summary: vi.fn(), pathname: "/COO/issues", collapsed: false, userId: "reviewer" }));
+const fixture = vi.hoisted(() => ({ attention: vi.fn(), summary: vi.fn(), pathname: "/COO/issues", collapsed: false, userId: "reviewer", chats: [] as Array<{ isUnreadForMe: boolean }> }));
 vi.mock("@/hooks/useAgentChatNavigation", () => ({ useAgentChatNavigation: () => ({
-  companyId: "company", userId: fixture.userId, agents: { data: [] }, chats: { data: [] }, session: { isSuccess: true },
+  companyId: "company", userId: fixture.userId, agents: { data: [] }, chats: { data: fixture.chats }, session: { isSuccess: true },
 }) }));
 vi.mock("@/hooks/useRecentTasks", () => ({ useRecentTasks: () => ({ entries: [] }) }));
 vi.mock("@/context/DialogContext", () => ({ useDialogActions: () => ({ openNewIssue: vi.fn() }) }));
@@ -43,12 +43,21 @@ function summary(items: AttentionItem[]) {
 let root: Root, container: HTMLDivElement, client: QueryClient;
 beforeEach(() => {
   vi.clearAllMocks(); localStorage.clear(); fixture.collapsed = false; fixture.userId = "reviewer"; fixture.pathname = "/COO/issues";
+  fixture.chats = [];
   fixture.summary.mockResolvedValue(summary([pending("question"), pending("review")]));
   container = document.createElement("div"); document.body.appendChild(container); root = createRoot(container);
   client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
 });
 
 describe("Coordinator pinned pages", () => {
+  it("announces unread chat totals in expanded and collapsed navigation", async () => {
+    fixture.chats = [{ isUnreadForMe: true }, { isUnreadForMe: false }, { isUnreadForMe: true }];
+    await renderSidebar();
+    expect(container.querySelector('a[href="/chats"] [aria-label="2 unread chats"]')).not.toBeNull();
+    fixture.collapsed = true;
+    await renderSidebar();
+    expect(container.querySelector('a[href="/chats"]')?.getAttribute("aria-label")).toBe("Chat, 2 unread chats");
+  });
   const pinnedPages = () => container.querySelector('[aria-label="Pinned pages"]');
   async function click(label: string) {
     const button = document.querySelector<HTMLButtonElement>(`button[aria-label="${label}"]`);

ui/src/components/CoordinatorSidebar.tsx

@@ -62,6 +62,7 @@ function ProjectRecent({ project }: { project: Project }) {
  * or task just because someone visits or switches agents. */
 export function CoordinatorSidebar({ children }: { children?: ReactNode }) {
   const { companyId, userId, agents, chats, session } = useAgentChatNavigation();
+  const unreadChatCount = chats.data?.filter(chat => chat.isUnreadForMe).length ?? 0;
   const pinnedNavigation = usePinnedNavigation(userId);
   const [moreOpen, setMoreOpen] = useState(false);
   const moreContentRef = useRef<HTMLDivElement>(null);
@@ -99,7 +100,7 @@ export function CoordinatorSidebar({ children }: { children?: ReactNode }) {
     <div className="design-sidebar-brand"><SidebarCompanyMenu showChevron={false} /></div>
     <nav className="design-sidebar-navigation" aria-label="Workspace navigation">
       <div className="design-sidebar-primary">
-        <SidebarNavItem className="design-sidebar-item" to="/chats" label="Chat" icon={MessageCircle} />
+        <SidebarNavItem className="design-sidebar-item" to="/chats" label="Chat" icon={MessageCircle} badge={unreadChatCount} badgeLabel="unread chats" />
         <div className="group/coordinator-new relative">
           <SidebarNavItem to="/issues" label="Tasks" icon={CircleCheck} className={cn("design-sidebar-item", !rail && "pr-9")} />
           {!rail && <button type="button" aria-label="New task" title="New task" onClick={() => openNewIssue()}

ui/src/components/Sidebar.tsx

@@ -33,6 +33,7 @@ import { SidebarAgents } from "./SidebarAgents";
 import { SidebarProjects } from "./SidebarProjects";
 import { SidebarStarredProjects } from "./SidebarStarredProjects";
 import { useAgentChatEnabled } from "@/hooks/useAgentChatEnabled";
+import { useAgentChatNavigation } from "@/hooks/useAgentChatNavigation";
 import { SidebarRecentTasks } from "./SidebarRecentTasks";
 import { useDialogActions } from "../context/DialogContext";
 import { useCompany } from "../context/CompanyContext";
@@ -60,6 +61,8 @@ export function Sidebar({ children }: { children?: ReactNode }) {
 function ClassicSidebar({ children }: { children?: ReactNode }) {
   const { openNewIssue } = useDialogActions();
   const { enabled: agentChatEnabled } = useAgentChatEnabled();
+  const chatNavigation = useAgentChatNavigation();
+  const unreadChatCount = chatNavigation.chats.data?.filter(chat => chat.isUnreadForMe).length ?? 0;
   // Every labeled section is collapsible (session-scoped, default open) —
   // one policy across static nav groups and the data-driven sections.
   const [workOpen, setWorkOpen] = useState(true);
@@ -192,7 +195,7 @@ function ClassicSidebar({ children }: { children?: ReactNode }) {
               alert={inboxBadge.failedRuns > 0}
             />
           ) : null}
-          {agentChatEnabled && !chatRail ? <SidebarNavItem to="/chats" label="Chat" icon={MessageCircle} /> : null}
+          {agentChatEnabled && !chatRail ? <SidebarNavItem to="/chats" label="Chat" icon={MessageCircle} badge={unreadChatCount} badgeLabel="unread chats" /> : null}
           {showDecisions ? (
             <SidebarNavItem
               to="/decisions"
@@ -215,7 +218,7 @@ function ClassicSidebar({ children }: { children?: ReactNode }) {
               agents you talk to live in the Chat surface's own secondary rail
               (ChatContextualSidebar), not in the primary nav. */}
           {chatRail ? (
-            <SidebarNavItem to="/chats" label="Chat" icon={MessageCircle} />
+            <SidebarNavItem to="/chats" label="Chat" icon={MessageCircle} badge={unreadChatCount} badgeLabel="unread chats" />
           ) : null}
           {/* Combined Inbox + Task List: Inbox is a view inside Tasks, so the
               unread/failed-run badge rides on Tasks. */}

ui/src/components/SidebarNavItem.tsx

@@ -198,6 +198,7 @@ export function SidebarNavItem({
       )}
       {!rail && hasBadge && (
         <Badge variant="ghost"
+          aria-label={badgeLabel ? `${badge} ${badgeLabel}` : undefined}
           className={cn(
             "ml-auto px-1.5 leading-none",
             badgeTone === "danger"

ui/src/components/task-chat/TaskChatBubble.tsx

@@ -1,4 +1,6 @@
 import { CoordinatorRelativeTime } from "@/components/coordinator/CoordinatorRelativeTime";
+import { useAgentChatRead } from "@/hooks/useAgentChatRead";
+import { Link } from "@/lib/router";
 import { useCoordinatorPresentation } from "@/components/coordinator/CoordinatorPresentation";
 import { TextAttachmentContext } from "@/context/TextAttachmentContext";
 import { useArtifactsV1Enabled } from "@/hooks/useArtifactsV1Enabled";
@@ -147,6 +149,7 @@ function TaskChatBubbleContent({
   onTryAgainNoLiveExecutionPath,
   tryAgainNoLiveExecutionPathPending,
 }: TaskChatBubbleProps) {
+  const readRef = useAgentChatRead(item.id, item.createdAtIso, item.author === "agent" && !item.optimistic);
   const streamlined = useStreamlinedTaskChatPresentation();
   const coordinator = useCoordinatorPresentation();
   const recordedTimestamp = item.createdAtIso ?? (typeof item.atMs === "number" && Number.isFinite(item.atMs) ? new Date(item.atMs) : null);
@@ -229,6 +232,7 @@ function TaskChatBubbleContent({
   return (
     <div
       data-conversation-message={isHuman ? "human" : "agent"}
+      ref={readRef}
       className={cn(
         "flex w-full flex-col gap-1",
         animateEntry && "tc-enter-bubble",
@@ -236,6 +240,9 @@ function TaskChatBubbleContent({
       )}
     >
       {beforeTurn ? <div className="w-full pb-1">{beforeTurn}</div> : null}
+      {item.chatMessage && <Link to={`/issues/${item.chatMessage.sourceTaskIdentifier}`} className="px-1 text-xs text-muted-foreground underline underline-offset-4">
+        From {item.chatMessage.sourceTaskIdentifier}
+      </Link>}
       {isHuman && !item.isCurrentUser && item.authorName ? (
         <span className="px-1 text-sm font-semibold text-foreground" data-testid="task-chat-human-identity" data-author-user-id={item.authorUserId}>
           <Identity name={item.authorName} avatarUrl={paperclipHumanAvatarUrl(item.authorAvatarUrl)} size="default" className="gap-2" />

ui/src/components/task-chat/task-chat-adapter.ts

@@ -136,6 +136,7 @@ export function commentsToTaskChatItems(
       agent: effectiveAgentId(comment) ? ctx.agentMap?.get(effectiveAgentId(comment)!) ?? { id: effectiveAgentId(comment)! } : undefined,
       text: comment.body,
       origin: comment.origin ?? "comment",
+      chatMessage: comment.metadata?.chatMessage,
       sourceChannel: kind === "human" ? comment.metadata?.sourceChannel : undefined,
       timestamp: formatTaskChatCommentTimestamp(comment, kind),
       optimistic,

ui/src/components/task-chat/task-chat-model.ts

@@ -165,6 +165,7 @@ export interface TaskChatMessageItem {
    */
   presentation?: IssueCommentPresentation | null;
   metadata?: IssueCommentMetadata | null;
+  chatMessage?: IssueCommentMetadata["chatMessage"];
   /** Agent that owns the source run, used to build run-detail links in metadata rows. */
   runAgentId?: string | null;
   /** Raw comment timestamp (ISO) — the collapsed system row shows relative time. */

ui/src/context/LiveUpdatesProvider.test.ts

@@ -16,6 +16,20 @@ import { __liveUpdatesTestUtils } from "./LiveUpdatesProvider";
 import { queryKeys } from "../lib/queryKeys";
 
 describe("LiveUpdatesProvider issue invalidation", () => {
+  it("discovers first proactive deliveries without invalidating another human's chat list", () => {
+    const client = new QueryClient();
+    const mine = queryKeys.agentChats.list("company-1", "user-1");
+    const theirs = queryKeys.agentChats.list("company-1", "user-2");
+    client.setQueryData(mine, []);
+    client.setQueryData(theirs, []);
+    __liveUpdatesTestUtils.invalidateActivityQueries(client, "company-1", {
+      entityType: "issue", entityId: "new-chat", action: "issue.comment_added",
+      details: { conversationUserId: "user-1", conversationAgentId: "kodi", commentId: "digest" },
+    }, { userId: "user-1", agentId: null });
+    expect(client.getQueryState(mine)?.isInvalidated).toBe(true);
+    expect(client.getQueryState(theirs)?.isInvalidated).toBe(false);
+    client.clear();
+  });
   it.each(["issue.thread_interaction_accepted", "issue.thread_interaction_answered", "decision.decided", "decision.effect_succeeded", "decision.effect_failed", "issue.conversation_session_started", "inbox.dismissed", "inbox.snoozed", "inbox.restored"])("refreshes canonical attention, history and source-chat projections after %s", action => {
     const client = new QueryClient();
     const invalidate = vi.spyOn(client, "invalidateQueries");

ui/src/context/LiveUpdatesProvider.tsx

@@ -1444,8 +1444,10 @@ function invalidateActivityQueries(
   if (entityType === "issue") {
     const chatListKey = queryKeys.agentChats.list(companyId, currentActor.userId);
     const knownChat = entityId && queryClient.getQueryData<Issue[]>(chatListKey)?.some(chat => chat.id === entityId);
-    if (knownChat || action === "issue.conversation_opened" && ownActorActivity) {
+    const ownChatDelivery = readString(details?.conversationUserId) === (currentActor.userId ?? "local-board");
+    if (knownChat || ownChatDelivery || action === "issue.conversation_opened" && ownActorActivity) {
       queryClient.invalidateQueries({ queryKey: chatListKey });
+      queryClient.invalidateQueries({ queryKey: ["agent-chat", companyId, currentActor.userId] });
     }
     if (action === "issue.tree_hold_created" || action === "issue.tree_hold_released" || action === "issue.updated") {
       // An ancestor hold or reparenting changes descendants' effective pause.

ui/src/hooks/useAgentChatRead.test.tsx

@@ -0,0 +1,158 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { AgentChatReadProvider, useAgentChatRead } from "./useAgentChatRead";
+import { ApiError } from "@/api/client";
+const markRead = vi.hoisted(() => vi.fn());
+vi.mock("@/api/issues", () => ({ issuesApi: { markRead } }));
+let root: Root, container: HTMLDivElement, client: QueryClient;
+let focused = true, latest = true, visible = true;
+const first = "11111111-1111-4111-8111-111111111111", second = "22222222-2222-4222-8222-222222222222";
+function Message({ id }: { id: string }) {
+  const ref = useAgentChatRead(id, "2026-10-30T12:00:00.123Z", true);
+  return <div ref={ref}>Digest</div>;
+}
+async function render(ids = [first], companyId = "company-1", userId = "human-1", issueId = "chat-1") {
+  await act(async () => root.render(<QueryClientProvider client={client}>
+    <AgentChatReadProvider issueId={issueId} companyId={companyId} userId={userId}>
+      <div className="task-chat-scroll-viewport">{ids.map(id => <Message key={id} id={id} />)}</div>
+    </AgentChatReadProvider>
+  </QueryClientProvider>));
+  await act(async () => { window.dispatchEvent(new Event("focus")); });
+}
+beforeEach(() => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  vi.stubGlobal("requestAnimationFrame", vi.fn(() => 1));
+  vi.stubGlobal("cancelAnimationFrame", vi.fn());
+  focused = true; latest = true; visible = true;
+  vi.spyOn(document, "hasFocus").mockImplementation(() => focused);
+  vi.spyOn(document, "visibilityState", "get").mockImplementation(() => visible ? "visible" : "hidden");
+  vi.spyOn(HTMLElement.prototype, "scrollHeight", "get").mockImplementation(() => latest ? 100 : 300);
+  vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(100);
+  vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({ top: 0, bottom: 100, height: 100, left: 0, right: 100, width: 100, x: 0, y: 0, toJSON() {} });
+  markRead.mockReset().mockResolvedValue({});
+  client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  container = document.createElement("div"); document.body.append(container); root = createRoot(container);
+});
+afterEach(async () => { await act(async () => root.unmount()); container.remove(); client.clear(); vi.useRealTimers(); vi.restoreAllMocks(); vi.unstubAllGlobals(); });
+it("reads only visible foreground messages at the bottom, including arrivals sharing a millisecond", async () => {
+  focused = false; await render(); expect(markRead).not.toHaveBeenCalled();
+  focused = true; latest = false; await render(); expect(markRead).not.toHaveBeenCalled();
+  latest = true; await render(); expect(markRead).toHaveBeenLastCalledWith("chat-1", first);
+  await render([first, second]); expect(markRead).toHaveBeenLastCalledWith("chat-1", second);
+  await render([first, second]); expect(markRead).toHaveBeenCalledTimes(2);
+});
+it("does not clear concurrent unseen arrivals while a read request is pending", async () => {
+  let finish!: () => void;
+  markRead.mockImplementationOnce(() => new Promise<void>(resolve => { finish = resolve; }));
+  await render(); expect(markRead).toHaveBeenCalledTimes(1);
+  focused = false; await render([first, second]);
+  await act(async () => finish()); expect(markRead).toHaveBeenCalledTimes(1);
+  focused = true; await render([first, second]); expect(markRead).toHaveBeenLastCalledWith("chat-1", second);
+});
+it("automatically retries a failed visible message without another focus event", async () => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  markRead.mockRejectedValueOnce(new TypeError("Network unavailable"));
+  await render();
+  expect(markRead).toHaveBeenCalledTimes(1);
+  await act(async () => { await vi.advanceTimersByTimeAsync(500); });
+  expect(markRead).toHaveBeenCalledTimes(2);
+  expect(markRead).toHaveBeenLastCalledWith("chat-1", first);
+  expect(container.querySelector('[role="alert"]')).toBeNull();
+  await act(async () => { await vi.advanceTimersByTimeAsync(60_000); });
+  expect(markRead).toHaveBeenCalledTimes(2);
+});
+it("retries only the seen cutoff when another message arrives out of view", async () => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  markRead.mockRejectedValueOnce(new TypeError("Network unavailable"));
+  await render();
+  focused = false; await render([first, second]);
+  await act(async () => { await vi.advanceTimersByTimeAsync(500); });
+  expect(markRead).toHaveBeenCalledTimes(2);
+  expect(markRead).toHaveBeenLastCalledWith("chat-1", first);
+  focused = true; await render([first, second]);
+  expect(markRead).toHaveBeenLastCalledWith("chat-1", second);
+});
+it("coalesces a newly seen message into the pending retry", async () => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  markRead.mockRejectedValueOnce(new TypeError("Network unavailable"));
+  await render();
+  await render([first, second]);
+  expect(markRead).toHaveBeenCalledTimes(1);
+  await act(async () => { await vi.advanceTimersByTimeAsync(500); });
+  expect(markRead).toHaveBeenCalledTimes(2);
+  expect(markRead).toHaveBeenLastCalledWith("chat-1", second);
+  await render([first, second]);
+  expect(markRead).toHaveBeenCalledTimes(2);
+});
+it("respects the server retry delay for a rate-limited read", async () => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  markRead.mockRejectedValueOnce(new ApiError("Rate limited", 429, {}, { retryAfterMs: 2_000 }));
+  await render();
+  await act(async () => { await vi.advanceTimersByTimeAsync(1_999); });
+  expect(markRead).toHaveBeenCalledTimes(1);
+  await act(async () => { await vi.advanceTimersByTimeAsync(1); });
+  expect(markRead).toHaveBeenCalledTimes(2);
+});
+it("stops after bounded retries and recovers the retained cutoff on reconnect", async () => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  markRead.mockRejectedValue(new ApiError("Unavailable", 503, {}));
+  await render();
+  await act(async () => { await vi.advanceTimersByTimeAsync(2_000); });
+  expect(markRead).toHaveBeenCalledTimes(3);
+  expect(container.querySelector('[role="alert"]')?.textContent).toBe("Couldn’t mark this chat read.");
+  await act(async () => { await vi.advanceTimersByTimeAsync(60_000); });
+  expect(markRead).toHaveBeenCalledTimes(3);
+  markRead.mockResolvedValue({});
+  await act(async () => { window.dispatchEvent(new Event("online")); });
+  expect(markRead).toHaveBeenCalledTimes(4);
+  expect(markRead).toHaveBeenLastCalledWith("chat-1", first);
+  expect(container.querySelector('[role="alert"]')).toBeNull();
+});
+it.each(["company", "human", "chat", "unmount"])("cancels a pending retry after %s changes", async kind => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  markRead.mockRejectedValue(new TypeError("Network unavailable"));
+  await render();
+  expect(markRead).toHaveBeenCalledTimes(1);
+  focused = false;
+  if (kind === "unmount") await act(async () => { root.render(null); });
+  else await render([first], kind === "company" ? "company-2" : "company-1", kind === "human" ? "human-2" : "human-1", kind === "chat" ? "chat-2" : "chat-1");
+  await act(async () => { await vi.advanceTimersByTimeAsync(60_000); });
+  expect(markRead).toHaveBeenCalledTimes(1);
+});
+it("resumes an exhausted cutoff when the chat becomes visible again", async () => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  markRead.mockRejectedValue(new TypeError("Network unavailable"));
+  await render();
+  await act(async () => { await vi.advanceTimersByTimeAsync(2_000); });
+  expect(markRead).toHaveBeenCalledTimes(3);
+  markRead.mockResolvedValue({});
+  visible = false;
+  await act(async () => { document.dispatchEvent(new Event("visibilitychange")); });
+  expect(markRead).toHaveBeenCalledTimes(3);
+  visible = true;
+  await act(async () => { document.dispatchEvent(new Event("visibilitychange")); });
+  expect(markRead).toHaveBeenCalledTimes(4);
+  expect(markRead).toHaveBeenLastCalledWith("chat-1", first);
+});
+it("does not retry a denied read receipt", async () => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  markRead.mockRejectedValue(new ApiError("Forbidden", 403, {}));
+  await render();
+  await act(async () => { await vi.advanceTimersByTimeAsync(60_000); });
+  expect(markRead).toHaveBeenCalledTimes(1);
+  expect(container.querySelector('[role="alert"]')?.textContent).toBe("Couldn’t mark this chat read.");
+});
+it("discards an in-flight failure after the human changes", async () => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  let fail!: (cause: Error) => void;
+  markRead.mockImplementationOnce(() => new Promise<void>((_, reject) => { fail = reject; }));
+  await render();
+  focused = false; await render([first], "company-1", "human-2");
+  await act(async () => { fail(new TypeError("Network unavailable")); });
+  await act(async () => { await vi.advanceTimersByTimeAsync(60_000); });
+  expect(markRead).toHaveBeenCalledTimes(1);
+  expect(container.querySelector('[role="alert"]')).toBeNull();
+});

ui/src/hooks/useAgentChatRead.tsx

@@ -0,0 +1,122 @@
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { isUuidLike } from "@paperclipai/shared";
+import { ApiError } from "@/api/client";
+import { issuesApi } from "@/api/issues";
+import { queryKeys } from "@/lib/queryKeys";
+
+type Seen = { id: string; at: number };
+const READ_RETRY_DELAYS = [500, 1_500];
+const ChatReadContext = createContext<((message: Seen) => void) | null>(null);
+
+export function AgentChatReadProvider({ issueId, companyId, userId, children }: {
+  issueId?: string; companyId: string; userId: string | null; children: ReactNode;
+}) {
+  const client = useQueryClient();
+  const [error, setError] = useState(false);
+  const scope = useMemo(() => ({ active: true, pending: null as Seen | null, seenIds: new Set<string>(), sentAt: -Infinity,
+    busy: false, failures: 0, exhausted: false, retryTimer: null as ReturnType<typeof setTimeout> | null }), [issueId, companyId, userId]);
+  const flush = useCallback(async function flush(): Promise<void> {
+    if (!issueId || !scope.active || scope.busy || scope.retryTimer !== null || scope.exhausted) return;
+    scope.busy = true;
+    try {
+      while (scope.active && scope.pending) {
+        const next = scope.pending;
+        try {
+          await issuesApi.markRead(issueId, next.id);
+        } catch (cause) {
+          if (!scope.active) return;
+          const retryable = !(cause instanceof ApiError) || cause.status === 408 || cause.status === 429 || cause.status >= 500;
+          const delay = READ_RETRY_DELAYS[scope.failures];
+          if (retryable && delay !== undefined) {
+            scope.failures += 1;
+            scope.retryTimer = setTimeout(() => { scope.retryTimer = null; void flush(); },
+              Math.max(delay, cause instanceof ApiError ? cause.retryAfterMs ?? 0 : 0));
+          } else {
+            scope.exhausted = true;
+            setError(true);
+          }
+          return;
+        }
+        if (!scope.active) return;
+        if (scope.pending?.id === next.id) scope.pending = null;
+        scope.sentAt = Math.max(scope.sentAt, next.at);
+        scope.failures = 0;
+        setError(false);
+        void client.invalidateQueries({ queryKey: queryKeys.agentChats.list(companyId, userId) });
+        void client.invalidateQueries({ queryKey: ["agent-chat", companyId, userId] });
+      }
+    } finally { scope.busy = false; }
+  }, [issueId, companyId, userId, client, scope]);
+  useEffect(() => {
+    scope.active = true;
+    setError(false);
+    if (scope.pending) {
+      scope.exhausted = false;
+      scope.failures = 0;
+      queueMicrotask(() => { void flush(); });
+    }
+    return () => {
+      scope.active = false;
+      if (scope.retryTimer !== null) { clearTimeout(scope.retryTimer); scope.retryTimer = null; }
+    };
+  }, [scope, flush]);
+  useEffect(() => {
+    const retry = () => {
+      if (document.visibilityState !== "visible" || !scope.active || !scope.exhausted || !scope.pending) return;
+      scope.exhausted = false;
+      scope.failures = 0;
+      setError(false);
+      void flush();
+    };
+    window.addEventListener("online", retry);
+    window.addEventListener("focus", retry);
+    document.addEventListener("visibilitychange", retry);
+    return () => {
+      window.removeEventListener("online", retry);
+      window.removeEventListener("focus", retry);
+      document.removeEventListener("visibilitychange", retry);
+    };
+  }, [scope, flush]);
+  const seen = useCallback((message: Seen) => {
+    if (!issueId || !scope.active || scope.seenIds.has(message.id) || message.at < scope.sentAt) return;
+    scope.seenIds.add(message.id);
+    if (!scope.pending || message.at >= scope.pending.at) scope.pending = message;
+    if (scope.exhausted) { scope.exhausted = false; scope.failures = 0; setError(false); }
+    if (!scope.busy && scope.retryTimer === null) queueMicrotask(() => { void flush(); });
+  }, [issueId, scope, flush]);
+  return <ChatReadContext.Provider value={issueId ? seen : null}>
+    {error && <p role="alert" className="text-sm text-destructive">Couldn’t mark this chat read.</p>}
+    {children}
+  </ChatReadContext.Provider>;
+}
+
+export function useAgentChatRead(id: string, createdAt: string | undefined, enabled: boolean) {
+  const seen = useContext(ChatReadContext);
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const element = ref.current;
+    if (!seen || !enabled || !element || !isUuidLike(id) || !createdAt) return;
+    const at = new Date(createdAt).getTime();
+    if (!Number.isFinite(at)) return;
+    const viewport = element.closest<HTMLElement>(".task-chat-scroll-viewport");
+    const check = () => {
+      if (document.visibilityState !== "visible" || !document.hasFocus() || !viewport) return;
+      if (viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight > 1) return;
+      const message = element.getBoundingClientRect(), bounds = viewport.getBoundingClientRect();
+      if (message.height > 0 && message.bottom <= bounds.bottom + 1 && message.bottom > bounds.top) seen({ id, at });
+    };
+    const observer = typeof IntersectionObserver === "undefined" ? null : new IntersectionObserver(check, { root: viewport });
+    observer?.observe(element);
+    viewport?.addEventListener("scroll", check, { passive: true });
+    document.addEventListener("visibilitychange", check);
+    window.addEventListener("focus", check);
+    const frame = requestAnimationFrame(check);
+    return () => {
+      cancelAnimationFrame(frame); observer?.disconnect();
+      viewport?.removeEventListener("scroll", check);
+      document.removeEventListener("visibilitychange", check); window.removeEventListener("focus", check);
+    };
+  }, [seen, id, createdAt, enabled]);
+  return ref;
+}

ui/src/pages/IssueDetail.test.tsx

@@ -1639,7 +1639,7 @@ describe("IssueDetail", () => {
     });
     await flushReact();
     expect(mockNavigate).not.toHaveBeenCalled();
-    expect(mockIssuesApi.markRead).toHaveBeenCalledWith(canonical.id);
+    expect(mockIssuesApi.markRead).not.toHaveBeenCalled();
     const [breadcrumbs] = mockSetBreadcrumbs.mock.calls.at(-1)!;
     expect(breadcrumbs[0].leading.type).toBe(AgentAvatar);
     expect(breadcrumbs[0].leading.props).toMatchObject({ agent, size: 24 });

ui/src/pages/IssueDetail.tsx

@@ -1,6 +1,7 @@
 import { useIssueIdBatches } from "@/hooks/useIssueIdBatches";
 import { useConversationHistoryPages, type ConversationHistoryPage } from "@/hooks/useConversationHistoryPages";
 import { taskChatHashAnchor } from "@/components/task-chat/scroll-navigation";
+import { AgentChatReadProvider } from "@/hooks/useAgentChatRead";
 import { useCoordinatorWorkspaceEnabled } from "@/hooks/useCoordinatorWorkspaceEnabled";
 import { CoordinatorAgentSwitcher } from "@/components/CoordinatorAgentSwitcher";
 import { TaskDecisionRecord } from "@/components/TaskDecisionRecord";
@@ -1956,6 +1957,7 @@ const IssueDetailChatTab = memo(function IssueDetailChatTab({
       }
     }
     const projectedComments = commentsToProject.map((comment) => {
+      if (comment.metadata?.chatMessage) return { ...comment, runId: null };
       const activityMeta = runMetaByCommentId.get(comment.id);
       // Internal run finalization can persist a reply without a separate
       // comment_added activity row. Its durable authoring run is stronger
@@ -6101,6 +6103,7 @@ export function TaskDetailSurface({ conversation, tasksTab }: { tasksTab?: TaskS
 
   useEffect(() => {
     if (!issueId || !issue?.id) return;
+    if (issue.conversationAgentId) return;
     if (lastMarkedReadIssueIdRef.current === issue.id) return;
     lastMarkedReadIssueIdRef.current = issue.id;
     markIssueRead.mutate(issue.id);
@@ -8082,6 +8085,7 @@ export function TaskDetailSurface({ conversation, tasksTab }: { tasksTab?: TaskS
 
   return (
     <FileViewerProvider issueId={conversation && !conversation.issue ? "" : issue.id} enabled={fileViewerEnabled}>
+      <AgentChatReadProvider issueId={issue.conversationAgentId && issue.conversationUserId === (currentUserId ?? "local-board") && (!conversation || conversation.issue) ? issue.id : undefined} companyId={issue.companyId} userId={currentUserId}>
       <TextAttachmentContext.Provider value={taskChatShellEnabled ? handleOpenTextAttachment : null}><IssueGalleryContext.Provider value={openIssueGallery}>
         <div
           data-task-chat-shell={taskChatShellEnabled ? "" : undefined}
@@ -8991,6 +8995,7 @@ export function TaskDetailSurface({ conversation, tasksTab }: { tasksTab?: TaskS
           <ScrollToBottom />
         </div>
       </IssueGalleryContext.Provider></TextAttachmentContext.Provider>
+      </AgentChatReadProvider>
     </FileViewerProvider>
   );
 }

ui/storybook/stories/agent-chat/agent-conversation-sidebar.stories.tsx

@@ -37,6 +37,13 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 export const Default: Story = { name: "01 · Agent list · Interactive" };
+export const UnreadMessages: Story = {
+  name: "11 · Proactive message unread",
+  args: { unreadAgentIds: [sidebarAgents[0].id] },
+  play: async ({ canvasElement }) => {
+    await expect(within(canvasElement).getByRole("img", { name: `Unread messages from ${sidebarAgents[0].name}` })).toBeVisible();
+  },
+};
 export const Search: Story = { name: "02 · Search by role", args: { initialSearch: "research" } };
 export const NoResults: Story = { name: "03 · No matches", args: { initialSearch: "accountant" } };
 export const Loading: Story = { name: "04 · Loading", args: { agents: [], availableAgents: [], loading: true } };

ui/storybook/stories/agent-chat/proactive-messages.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { TaskChatBubble } from "@/components/task-chat/TaskChatBubble";
+import type { TaskChatMessageItem } from "@/components/task-chat/task-chat-model";
+import { prepareProactiveMessageFixtures, ProactiveMessageReview } from "../../support/agent-chat/proactive-messages";
+
+const message: TaskChatMessageItem = {
+  id: "digest", kind: "message", author: "agent", authorName: "Kodi",
+  text: "## Morning PR digest\n\nThree PRs need your review:\n\n- **#124** — Fix chat reconnect\n- **#127** — Improve task search\n- **#130** — Add release notes",
+  timestamp: "7:00 AM",
+  chatMessage: { sourceTaskId: "11111111-1111-4111-8111-111111111111", sourceTaskIdentifier: "PC-42",
+    sourceRunId: "22222222-2222-4222-8222-222222222222", contentHash: "0".repeat(64) },
+};
+const meta = {
+  id: "agent-chat-proactive-messages",
+  title: "Tasks and conversations/Agent conversations and project handoff/Proactive messages",
+  component: TaskChatBubble,
+  args: { item: message, animateEntry: false },
+  render: args => <div className="mx-auto max-w-2xl p-6"><TaskChatBubble {...args} /></div>,
+  parameters: { layout: "padded", initialEntries: ["/PAP/chats"], paperclip: {
+    capabilities: ["agent-chat/history", "agent-chat/discovery"], status: "current", implementation: "production", boundary: "fixtures",
+    notes: "Production Sidebar, CoordinatorSidebar, AgentConversationsSidebar, TaskChatBubble and read-receipt hook in a review-only gallery. Stateful API fixtures show unread-to-read and error transitions. The app navigation is currently expanded; the retired rail is not recreated. Server delivery, event refresh, account isolation, routine execution and real source-task navigation require the separate app/database checks.",
+  } },
+  beforeEach: ({ parameters }) => prepareProactiveMessageFixtures(parameters.readFailure === true, Number(parameters.transientReadFailures ?? 0)).cleanup,
+} satisfies Meta<typeof TaskChatBubble>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const AllChangedUx: Story = {
+  name: "01 · All changed UX",
+  parameters: { layout: "fullscreen", options: { showPanel: false } },
+  render: () => <ProactiveMessageReview />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(await canvas.findByRole("img", { name: "Unread messages from Kodi" })).toBeVisible();
+    await expect(canvas.getByRole("img", { name: "Unread messages from Mira" })).toBeVisible();
+    await expect(canvas.findAllByLabelText("2 unread chats")).resolves.toHaveLength(2);
+    await expect(canvas.getByRole("link", { name: "From PAP-42" })).toHaveAttribute("href", expect.stringContaining("/issues/PAP-42"));
+  },
+};
+export const ReadOnOpen: Story = {
+  ...AllChangedUx,
+  name: "02 · Open chat marks the rendered message read",
+  parameters: { layout: "fullscreen", options: { showPanel: true } },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByRole("img", { name: "Unread messages from Kodi" });
+    await userEvent.click(canvas.getByRole("button", { name: "Open Kodi chat" }));
+    await waitFor(() => expect(canvas.queryByRole("img", { name: "Unread messages from Kodi" })).not.toBeInTheDocument());
+    await expect(canvas.getByRole("img", { name: "Unread messages from Mira" })).toBeVisible();
+    await expect(canvas.findAllByLabelText("1 unread chats")).resolves.toHaveLength(2);
+  },
+};
+export const ReadAutomaticallyRecovers: Story = {
+  ...AllChangedUx,
+  name: "03 · Read receipt recovers automatically",
+  parameters: { layout: "fullscreen", options: { showPanel: true }, transientReadFailures: 1 },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByRole("img", { name: "Unread messages from Kodi" });
+    await userEvent.click(canvas.getByRole("button", { name: "Open Kodi chat" }));
+    await waitFor(() => expect(canvas.queryByRole("img", { name: "Unread messages from Kodi" })).not.toBeInTheDocument(), { timeout: 5_000 });
+    await expect(canvas.queryByRole("alert")).not.toBeInTheDocument();
+    await expect(canvas.findAllByLabelText("1 unread chats")).resolves.toHaveLength(2);
+  },
+};
+export const ReadReceiptFailure: Story = {
+  ...AllChangedUx,
+  name: "04 · Read receipt failed after retries",
+  parameters: { layout: "fullscreen", options: { showPanel: true }, readFailure: true },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByRole("img", { name: "Unread messages from Kodi" });
+    await userEvent.click(canvas.getByRole("button", { name: "Open Kodi chat" }));
+    await expect(await canvas.findByRole("alert", {}, { timeout: 5_000 })).toHaveTextContent("Couldn’t mark this chat read.");
+    await expect(canvas.getByRole("img", { name: "Unread messages from Kodi" })).toBeVisible();
+    await expect(canvas.findAllByLabelText("2 unread chats")).resolves.toHaveLength(2);
+  },
+};
+export const MobileReview: Story = { ...AllChangedUx, name: "05 · All changed UX · Mobile", globals: { viewport: { value: "mobile", isRotated: false } } };
+export const LightReview: Story = { ...AllChangedUx, name: "06 · All changed UX · Light", globals: { theme: "light" } };
+export const MorningDigest: Story = {
+  play: async ({ canvasElement }) => {
+    await expect(within(canvasElement).getByRole("link", { name: "From PC-42" })).toHaveAttribute("href", expect.stringContaining("/issues/PC-42"));
+  },
+};
+export const Mobile: Story = { globals: { viewport: { value: "mobile", isRotated: false } } };
+export const Light: Story = { globals: { theme: "light" } };

ui/storybook/support/agent-chat/proactive-messages.tsx

@@ -0,0 +1,119 @@
+import { useState } from "react";
+import { instanceExperimentalSettingsSchema, type Issue } from "@paperclipai/shared";
+import { Sidebar } from "@/components/Sidebar";
+import { CoordinatorSidebar } from "@/components/CoordinatorSidebar";
+import { AgentConversationsSidebar } from "@/components/AgentConversationsSidebar";
+import { TaskChatBubble } from "@/components/task-chat/TaskChatBubble";
+import type { TaskChatMessageItem } from "@/components/task-chat/task-chat-model";
+import { Button } from "@/components/ui/button";
+import { AgentChatReadProvider } from "@/hooks/useAgentChatRead";
+import { PluginLauncherProvider } from "@/plugins/launchers";
+import { useLocation, useNavigate } from "@/lib/router";
+import { storybookAgents, storybookIssues } from "../../fixtures/paperclipData";
+import { prepareFixtureApi } from "../capability-gaps/api";
+
+export const proactiveCompanyId = "company-storybook";
+export const proactiveChatId = "33333333-3333-4333-8333-333333333333";
+export const proactiveMessage: TaskChatMessageItem = {
+  id: "44444444-4444-4444-8444-444444444444",
+  kind: "message",
+  author: "agent",
+  authorName: "Kodi",
+  text: "## Morning PR digest\n\nThree PRs need your review:\n\n- **#124** — Fix chat reconnect\n- **#127** — Improve task search\n- **#130** — Add release notes",
+  timestamp: "7:00 AM",
+  createdAtIso: "2026-10-30T07:00:00.000Z",
+  chatMessage: {
+    sourceTaskId: "11111111-1111-4111-8111-111111111111",
+    sourceTaskIdentifier: "PAP-42",
+    sourceRunId: "22222222-2222-4222-8222-222222222222",
+    contentHash: "0".repeat(64),
+  },
+};
+
+const agents = [
+  { ...storybookAgents[0], name: "Kodi", urlKey: "kodi", status: "idle" as const, title: "Coding and pull requests" },
+  { ...storybookAgents[1], name: "Mira", urlKey: "mira", status: "idle" as const, title: "Research and planning" },
+];
+
+export function prepareProactiveMessageFixtures(readFailure = false, transientReadFailures = 0) {
+  const unread = new Set(agents.map(agent => agent.id));
+  let remainingReadFailures = transientReadFailures;
+  const chats = () => agents.map((agent, index): Issue => ({
+    ...storybookIssues[0],
+    id: index === 0 ? proactiveChatId : "55555555-5555-4555-8555-555555555555",
+    companyId: proactiveCompanyId,
+    title: `Chat with ${agent.name}`,
+    identifier: `PAP-${index + 100}`,
+    assigneeAgentId: agent.id,
+    conversationAgentId: agent.id,
+    conversationUserId: "user-board",
+    conversationState: "waiting",
+    status: "in_review",
+    projectId: null,
+    executionRunId: null,
+    updatedAt: new Date(index === 0 ? "2026-10-30T07:00:00Z" : "2026-10-30T06:45:00Z"),
+    isUnreadForMe: unread.has(agent.id),
+  }));
+  return prepareFixtureApi([
+    { path: "/api/instance/settings/experimental", read: () => instanceExperimentalSettingsSchema.parse({ enableAgentChat: true }) },
+    { path: "/api/workspace-preferences/me", read: () => ({ userId: "user-board", coordinatorWorkspaceEnabled: false }) },
+    { path: `/api/companies/${proactiveCompanyId}/agents`, read: () => agents },
+    { path: `/api/companies/${proactiveCompanyId}/chats`, read: chats },
+    { path: `/api/companies/${proactiveCompanyId}/projects`, read: () => [] },
+    { path: `/api/companies/${proactiveCompanyId}/live-runs`, read: () => [] },
+    { path: `/api/companies/${proactiveCompanyId}/attention`, read: () => ({ companyId: proactiveCompanyId, totalCount: 0, deskBadgeCount: 0, items: [], nextCursor: null }) },
+    { path: `/api/companies/${proactiveCompanyId}/resource-memberships/me`, read: () => ({ projectMemberships: {}, agentMemberships: {}, starredProjectIds: [], starredAgentIds: [], starredDocumentIds: [], updatedAt: null }) },
+    { path: "/api/cli-auth/me", read: () => ({ userId: "user-board", isInstanceAdmin: false, companyIds: [proactiveCompanyId], source: "authenticated", keyId: null, memberships: [{ companyId: proactiveCompanyId, membershipRole: "owner", status: "active" }] }) },
+    { path: `/api/issues/${proactiveChatId}/read`, method: "POST", read: ({ body }) => {
+      if (body.throughCommentId !== proactiveMessage.id) return Response.json({ error: "Expected the rendered message cutoff." }, { status: 400 });
+      if (readFailure || remainingReadFailures > 0) {
+        remainingReadFailures = Math.max(0, remainingReadFailures - 1);
+        return Response.json({ error: "Read receipt unavailable." }, { status: 503 });
+      }
+      unread.delete(agents[0].id);
+      return { issueId: proactiveChatId, userId: "user-board", lastReadAt: proactiveMessage.createdAtIso };
+    } },
+  ]);
+}
+
+export function ProactiveMessageReview() {
+  const navigate = useNavigate();
+  const { pathname } = useLocation();
+  const open = pathname.endsWith("/chats/kodi");
+  const [opened, setOpened] = useState(false);
+  return <main className="paperclip-story">
+    <div className="paperclip-story__inner space-y-6">
+      <header className="space-y-2">
+        <p className="paperclip-story__label">Proactive agent messages · changed UX</p>
+        <h1 className="text-2xl font-semibold">Kodi’s morning digest is waiting in chat</h1>
+        <p className="max-w-3xl text-sm text-muted-foreground">Both Chat navigation variants count unread chats. Each agent has its own unread dot. Open Kodi at the latest message to clear its dot and reduce the count; Mira stays unread.</p>
+      </header>
+      <div className="grid gap-4 md:grid-cols-3">
+        <section aria-label="Classic navigation" className="paperclip-story__frame overflow-hidden">
+          <h2 className="border-b border-border px-4 py-3 text-sm font-medium">Classic navigation</h2>
+          <div className="h-80 overflow-auto"><PluginLauncherProvider><Sidebar /></PluginLauncherProvider></div>
+        </section>
+        <section aria-label="Coordinator navigation" className="paperclip-story__frame overflow-hidden">
+          <h2 className="border-b border-border px-4 py-3 text-sm font-medium">Coordinator navigation</h2>
+          <div className="coordinator-workspace h-80 overflow-auto"><CoordinatorSidebar /></div>
+        </section>
+        <section aria-label="Agent unread messages" className="paperclip-story__frame overflow-hidden">
+          <h2 className="border-b border-border px-4 py-3 text-sm font-medium">Unread by agent</h2>
+          <div className="h-80"><AgentConversationsSidebar /></div>
+        </section>
+      </div>
+      <section aria-label="Kodi proactive digest" className="paperclip-story__frame overflow-hidden">
+        <div className="flex flex-wrap items-center justify-between gap-3 border-b border-border px-4 py-3">
+          <div><h2 className="text-sm font-medium">Chat with Kodi</h2><p className="text-xs text-muted-foreground">A normal agent message with a link to its source task</p></div>
+          <Button variant="outline" onClick={() => { setOpened(true); navigate("/chats/kodi"); }}>Open Kodi chat</Button>
+        </div>
+        <AgentChatReadProvider issueId={open && opened ? proactiveChatId : undefined} companyId={proactiveCompanyId} userId="user-board">
+          <div className="task-chat-scroll-viewport h-96 overflow-auto p-6" tabIndex={0} aria-label="Kodi latest messages">
+            <div className="mx-auto max-w-3xl"><TaskChatBubble item={proactiveMessage} animateEntry={false} /></div>
+          </div>
+        </AgentChatReadProvider>
+      </section>
+      <p className="text-xs text-muted-foreground">Production navigation, agent list, message bubble and read-receipt hook with isolated API fixtures. Server delivery, live events, account isolation and routine execution are verified by separate app tests.</p>
+    </div>
+  </main>;
+}