fraim-hub 2.0.315 → 2.0.316

package/dist/src/ai-hub/atomic-json-file.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renameWithRetry = renameWithRetry;
 exports.writeJsonAtomic = writeJsonAtomic;
+exports.writeFileAtomic = writeFileAtomic;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 // Atomic JSON file write for the conversation store and its derived caches.
@@ -47,9 +48,23 @@ function renameWithRetry(from, to) {
  * writing the same destination cannot collide on the temp file itself.
  */
 function writeJsonAtomic(filePath, value) {
+    writeFileAtomic(filePath, JSON.stringify(value), 'utf8');
+}
+/**
+ * Write-temp-then-rename for arbitrary content (binary or text) — the same durability guarantee
+ * as `writeJsonAtomic` without the JSON serialization step. Issue #1651: attachment blobs need the
+ * identical atomic-write + Windows-retry discipline as conversation JSON, so this is the shared
+ * primitive both now go through rather than a second copy of the temp-write+rename dance.
+ */
+function writeFileAtomic(filePath, data, encoding) {
     fs_1.default.mkdirSync(path_1.default.dirname(filePath), { recursive: true });
     const tempPath = `${filePath}.${process.pid}.${tempSeq++}.tmp`;
-    fs_1.default.writeFileSync(tempPath, JSON.stringify(value), 'utf8');
+    if (typeof data === 'string') {
+        fs_1.default.writeFileSync(tempPath, data, encoding || 'utf8');
+    }
+    else {
+        fs_1.default.writeFileSync(tempPath, data);
+    }
     try {
         renameWithRetry(tempPath, filePath);
     }

package/dist/src/ai-hub/attachment-store.js

@@ -0,0 +1,137 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentRejectedError = exports.MAX_ATTACHMENTS_PER_SEND = exports.MAX_UPLOAD_BODY_BYTES = exports.MAX_ATTACHMENT_BYTES = exports.ACCEPTED_ATTACHMENT_MIME_TYPES = void 0;
+exports.assertAttachmentUploadAllowed = assertAttachmentUploadAllowed;
+exports.sanitizeAttachmentBuffer = sanitizeAttachmentBuffer;
+exports.safeAttachmentBaseName = safeAttachmentBaseName;
+exports.attachmentDiskFilename = attachmentDiskFilename;
+exports.safeAttachmentMetaPath = safeAttachmentMetaPath;
+/**
+ * Hub message attachments — Issue #1651 (Hub attachments and screenshots).
+ *
+ * Deterministic, dependency-isolated helpers for validating and sanitizing a
+ * manager-uploaded attachment before it ever reaches disk. Kept separate from
+ * `server.ts` so the route handler stays a thin composition of these pure
+ * steps (architecture-standards §2/§3).
+ *
+ * Security posture (spec R10/R11, technical design "Sanitization"): an
+ * uploaded file is untrusted input. Images are re-encoded (not merely
+ * renamed/copied) via `sharp`, which strips any non-pixel payload — embedded
+ * scripts, polyglot content appended after the image's real end-of-data
+ * marker — as an inherent side effect of decoding + re-encoding pixel data.
+ * PDFs are scanned for `/JavaScript` / `/JS` object markers and rejected if
+ * found; this is a narrow heuristic, not a full sanitizer (documented as a
+ * known limitation in the technical design, not a claimed complete defense).
+ * Plain text/log files are stored unmodified — this delivery model (R12)
+ * never renders or executes attachment content, only hands the agent a file
+ * path its own file-read tool opens.
+ */
+const path_1 = __importDefault(require("path"));
+const sharp_1 = __importDefault(require("sharp"));
+/** Accepted upload MIME types (spec R1/R11). */
+exports.ACCEPTED_ATTACHMENT_MIME_TYPES = new Set([
+    'image/png',
+    'image/jpeg',
+    'image/gif',
+    'application/pdf',
+    'text/plain',
+]);
+const IMAGE_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif']);
+/** Per-file cap (spec R5/R11): matches the client-side pre-check exactly. */
+exports.MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+/**
+ * Server route body-size cap (technical design "Server-side enforcement"): 1 MB
+ * headroom above `MAX_ATTACHMENT_BYTES` absorbs transfer overhead. The 10 MB
+ * per-file cap itself is still enforced explicitly against the decoded body
+ * length so a file just under this outer limit but over the real cap is a
+ * clean 413, not a silent accept.
+ */
+exports.MAX_UPLOAD_BODY_BYTES = 11 * 1024 * 1024;
+/** Design-owned bound (technical design "Count/size bounds not specified by the spec"). */
+exports.MAX_ATTACHMENTS_PER_SEND = 5;
+/** Thrown by validation/sanitization for a request-level (never a server-fault) rejection. */
+class AttachmentRejectedError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.name = 'AttachmentRejectedError';
+        this.status = status;
+    }
+}
+exports.AttachmentRejectedError = AttachmentRejectedError;
+/** R11: server-side size/type enforcement, independent of the client-side R5 check. */
+function assertAttachmentUploadAllowed(mimeType, sizeBytes) {
+    if (!exports.ACCEPTED_ATTACHMENT_MIME_TYPES.has(mimeType)) {
+        throw new AttachmentRejectedError(415, `Unsupported attachment type: ${mimeType || '(none)'}`);
+    }
+    if (sizeBytes > exports.MAX_ATTACHMENT_BYTES) {
+        throw new AttachmentRejectedError(413, `Attachment exceeds the ${exports.MAX_ATTACHMENT_BYTES / (1024 * 1024)} MB limit.`);
+    }
+}
+/**
+ * PDF `/JavaScript` or `/JS` object-marker scan (technical design "Sanitization").
+ * Deliberately narrow: this is a reject-on-suspicious-marker gate, not a full
+ * PDF parser or sanitizer — sufficient because R1 requires only safe storage
+ * and a later file-path handoff to the agent (R12), never PDF rendering.
+ */
+function pdfContainsScriptMarker(buffer) {
+    // Scan the raw bytes as latin1 so multi-byte content can't hide a marker;
+    // PDF object names are always ASCII (`/JavaScript`, `/JS`).
+    const text = buffer.toString('latin1');
+    return /\/JavaScript\b/.test(text) || /\/JS\b/.test(text);
+}
+/**
+ * Re-encode an image (stripping any non-pixel payload) or reject a suspicious
+ * PDF. Text/plain passes through unmodified. Throws `AttachmentRejectedError`
+ * for a PDF script marker or a buffer `sharp` cannot decode as a valid image.
+ */
+async function sanitizeAttachmentBuffer(buffer, mimeType) {
+    if (IMAGE_MIME_TYPES.has(mimeType)) {
+        try {
+            const format = mimeType === 'image/jpeg' ? 'jpeg' : mimeType === 'image/gif' ? 'gif' : 'png';
+            return await (0, sharp_1.default)(buffer).toFormat(format).toBuffer();
+        }
+        catch (err) {
+            throw new AttachmentRejectedError(415, `Not a valid ${mimeType} image.`);
+        }
+    }
+    if (mimeType === 'application/pdf') {
+        if (pdfContainsScriptMarker(buffer)) {
+            throw new AttachmentRejectedError(415, 'PDF contains an embedded script marker and was rejected.');
+        }
+        return buffer;
+    }
+    // text/plain (the only remaining accepted type): no execution surface in
+    // this delivery model, stored as-is.
+    return buffer;
+}
+/** Strip path separators/control characters and cap length for a disk-safe filename. */
+function safeAttachmentBaseName(filename) {
+    const trimmed = typeof filename === 'string' ? filename.trim() : '';
+    // eslint-disable-next-line no-control-regex
+    const cleaned = trimmed.replace(/[\\/:*?"<>|\x00-\x1f]/g, '_').slice(0, 150);
+    return cleaned || 'file';
+}
+/** Disk filename for an attachment: `<id>-<safeName>` (technical design "Storage"). */
+function attachmentDiskFilename(id, filename) {
+    return `${id}-${safeAttachmentBaseName(filename)}`;
+}
+/**
+ * Resolve `<dir>/<id>.meta.json`, rejecting an `id` that would escape `dir`.
+ *
+ * Security: `id` reaches this function from a URL route param (`GET .../attachments/:attachmentId`)
+ * or a client-supplied `attachmentIds[]` entry (message send) with no format constraint of its own —
+ * `attachmentsDirFor` only validates `conversationId`, not this per-attachment id. Without this
+ * check, an id like `../../../etc/passwd` would let a caller read (or, combined with a write path,
+ * write) outside the intended attachments directory via ordinary `path.join`/`path.resolve` `..`
+ * handling.
+ */
+function safeAttachmentMetaPath(dir, id) {
+    const metaPath = path_1.default.resolve(dir, `${id}.meta.json`);
+    if (!metaPath.startsWith(path_1.default.resolve(dir) + path_1.default.sep)) {
+        throw new Error('Invalid attachment id.');
+    }
+    return metaPath;
+}

package/dist/src/ai-hub/conversation-store.js

@@ -440,6 +440,34 @@ class AiHubConversationStore {
     lockPath(bucketDir) {
         return path_1.default.join(bucketDir, '.lock');
     }
+    /**
+     * Directory holding attachment blobs for one conversation, nested inside that
+     * conversation's own bucket directory (issue #1651).
+     *
+     * This is the only sanctioned entry point into bucket-path resolution for
+     * attachments — every other module reaches attachment storage through this
+     * method rather than re-deriving the bucket key, so `bucketKey`'s sentinel
+     * handling (`@manager`/`@company`) stays centralized in one place. Nesting
+     * under the bucket directory (rather than a sibling root) means
+     * `removeProject`'s existing recursive delete already reaches attachments
+     * with no new deletion code — see the technical design's Correction 1.
+     */
+    attachmentsDirFor(bucketKey, conversationId) {
+        const key = normalizeConversationKey(bucketKey);
+        const attachmentsRoot = path_1.default.join(this.bucketDir(key), 'attachments');
+        const dir = path_1.default.resolve(attachmentsRoot, conversationId);
+        // Security: conversationId arrives from a URL route param / client-supplied
+        // field with no format constraint (it is not required to be a UUID). Without
+        // this containment check, a conversationId like '../../../etc' would resolve
+        // outside attachmentsRoot via path.resolve's own '..' handling, giving an
+        // attacker a write primitive (upload) and read primitive (download/message
+        // send) onto arbitrary paths on disk. Reject anything that does not resolve
+        // to a direct child of attachmentsRoot.
+        if (!dir.startsWith(attachmentsRoot + path_1.default.sep)) {
+            throw new Error('Invalid conversationId.');
+        }
+        return dir;
+    }
     invalidateProjectPathCache() {
         this.projectPathCache = null;
     }

package/dist/src/ai-hub/hosts.js

@@ -3060,12 +3060,15 @@ class ScriptedHostRuntime {
     }
 }
 exports.ScriptedHostRuntime = ScriptedHostRuntime;
-const createHubMessage = (role, text, deliveryStatus) => ({
+const createHubMessage = (role, text, deliveryStatus, 
+// Issue #1651: files/screenshots the manager attached to this message.
+attachments) => ({
     id: (0, crypto_1.randomUUID)(),
     role,
     text,
     createdAt: new Date().toISOString(),
     ...(deliveryStatus ? { deliveryStatus } : {}),
+    ...(attachments && attachments.length > 0 ? { attachments } : {}),
 });
 exports.createHubMessage = createHubMessage;
 const createHubEvent = (channel, text) => ({

package/dist/src/ai-hub/server.js

@@ -70,6 +70,8 @@ const manager_turns_1 = require("./manager-turns");
 const preferences_1 = require("./preferences");
 const conversation_store_1 = require("./conversation-store");
 const raw_event_log_store_1 = require("./raw-event-log-store");
+const atomic_json_file_1 = require("./atomic-json-file");
+const attachment_store_1 = require("./attachment-store");
 const hub_main_diagnostics_1 = require("./hub-main-diagnostics");
 const run_working_directory_1 = require("./run-working-directory");
 const conversation_search_1 = require("./conversation-search");
@@ -3974,6 +3976,12 @@ class AiHubServer {
                     text: message.text,
                     createdAt: message.createdAt,
                     ...(Number.isFinite(at) && at > 0 ? { at } : {}),
+                    // Issue #1651: attachment metadata must survive the run -> persisted-record
+                    // fold, or a reloaded conversation loses its attachment chips even though
+                    // the blobs remain on disk (Wire All Read Paths discipline).
+                    ...(Array.isArray(message.attachments) && message.attachments.length > 0
+                        ? { attachments: message.attachments }
+                        : {}),
                 };
             }),
             events: run.events.map((event) => ({
@@ -5110,6 +5118,38 @@ class AiHubServer {
         ].filter(Boolean).join('\n\n');
         return this.prepareStartPayload(deployment.projectPath, deployment.hostId, deployment.jobId, context);
     }
+    /**
+     * Issue #1651 R7/R12: resolve staged attachment ids (uploaded via
+     * POST /api/ai-hub/conversations/:conversationId/attachments) into persisted
+     * metadata for AiHubMessage.attachments, plus a "[Attached: ...]" reference
+     * suffix appended to the host-bound message text. An id that fails to
+     * resolve (already deleted, wrong conversation) is skipped rather than
+     * failing the whole send — the manager's own text still reaches the agent.
+     */
+    resolveMessageAttachments(bucketKey, conversationId, attachmentIds) {
+        const ids = Array.isArray(attachmentIds)
+            ? attachmentIds.filter((id) => typeof id === 'string' && id.trim().length > 0)
+            : [];
+        if (ids.length === 0)
+            return { attachments: undefined, referenceSuffix: '' };
+        const dir = this.conversationStore.attachmentsDirFor(bucketKey, conversationId);
+        const attachments = [];
+        const refLines = [];
+        for (const id of ids) {
+            try {
+                const raw = JSON.parse(fs_1.default.readFileSync((0, attachment_store_1.safeAttachmentMetaPath)(dir, id), 'utf8'));
+                attachments.push({ id: raw.id, filename: raw.filename, sizeBytes: raw.sizeBytes, mimeType: raw.mimeType });
+                refLines.push(`[Attached: ${raw.filename} at ${path_1.default.resolve(path_1.default.join(dir, raw.diskFilename))}]`);
+            }
+            catch {
+                // Stale/unknown/path-escaping attachment id — skip; the message still sends.
+            }
+        }
+        return {
+            attachments: attachments.length > 0 ? attachments : undefined,
+            referenceSuffix: refLines.length > 0 ? `\n${refLines.join('\n')}` : '',
+        };
+    }
     prepareContinueMessage(run, instructions, coachingJobId) {
         // coachingJobId is set when the user selected a manager coaching template
         // (e.g. follow-your-mentor). When present, it overrides the run's own jobId
@@ -5972,6 +6012,78 @@ class AiHubServer {
                 return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not switch agents.' });
             }
         });
+        // Issue #1651: Hub message attachments — binary upload transport.
+        // Route-scoped raw body parser (never `app.use()` at global scope): the client sends the
+        // attachment's real MIME type as Content-Type (image/png, application/pdf, ...), never
+        // application/json or multipart/*. express.json() (registered globally above) only consumes
+        // the request stream when req.is('json') matches; for any other Content-Type it calls next()
+        // without touching the stream, leaving it untouched for this route's express.raw() — confirmed
+        // by a real spike against this exact middleware order (see the technical design's "Spike
+        // Findings") and pinned by the byte-identity regression test in test-ai-hub-attachments.ts.
+        this.app.post('/api/ai-hub/conversations/:conversationId/attachments', express_1.default.raw({ type: () => true, limit: attachment_store_1.MAX_UPLOAD_BODY_BYTES }), async (req, res) => {
+            try {
+                const conversationId = req.params.conversationId;
+                const scope = scopeParam(req.query.scope);
+                if (!scope && (typeof req.query.projectPath !== 'string' || req.query.projectPath.trim().length === 0)) {
+                    return res.status(400).json({ error: 'projectPath required for project conversations' });
+                }
+                const bucketKey = scope ? (0, conversation_store_1.conversationScopeKey)(scope, '') : ensureDirectoryPath(req.query.projectPath);
+                const body = req.body;
+                if (!Buffer.isBuffer(body) || body.length === 0) {
+                    return res.status(400).json({ error: 'Expected a non-empty binary request body.' });
+                }
+                const mimeType = (req.headers['content-type'] || '').toString().split(';')[0].trim().toLowerCase();
+                (0, attachment_store_1.assertAttachmentUploadAllowed)(mimeType, body.length);
+                const filenameHeader = req.headers['x-attachment-filename'];
+                let rawFilename = 'attachment';
+                if (typeof filenameHeader === 'string' && filenameHeader) {
+                    try {
+                        rawFilename = decodeURIComponent(filenameHeader);
+                    }
+                    catch {
+                        rawFilename = filenameHeader;
+                    }
+                }
+                const sanitized = await (0, attachment_store_1.sanitizeAttachmentBuffer)(body, mimeType);
+                const id = (0, crypto_1.randomUUID)();
+                const dir = this.conversationStore.attachmentsDirFor(bucketKey, conversationId);
+                const diskFilename = (0, attachment_store_1.attachmentDiskFilename)(id, rawFilename);
+                const filename = (0, attachment_store_1.safeAttachmentBaseName)(rawFilename);
+                (0, atomic_json_file_1.writeFileAtomic)(path_1.default.join(dir, diskFilename), sanitized);
+                (0, atomic_json_file_1.writeFileAtomic)(path_1.default.join(dir, `${id}.meta.json`), JSON.stringify({ id, filename, sizeBytes: sanitized.length, mimeType, diskFilename }));
+                console.info('[ai-hub] hub.attachment_uploaded', { conversationId, id, mimeType, sizeBytes: sanitized.length });
+                return res.status(201).json({ id, filename, sizeBytes: sanitized.length, mimeType });
+            }
+            catch (error) {
+                if (error instanceof attachment_store_1.AttachmentRejectedError) {
+                    console.warn('[ai-hub] hub.attachment_rejected', { status: error.status, reason: error.message });
+                    return res.status(error.status).json({ error: error.message });
+                }
+                console.error('[ai-hub] hub.attachment_upload_failed', error instanceof Error ? error.message : error);
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Attachment upload failed.' });
+            }
+        });
+        // Issue #1651: byte-serve one attachment for transcript thumbnail/chip rendering
+        // (`<img src="...">` for images; metadata-driven chip for everything else).
+        this.app.get('/api/ai-hub/conversations/:conversationId/attachments/:attachmentId', (req, res) => {
+            try {
+                const scope = scopeParam(req.query.scope);
+                if (!scope && (typeof req.query.projectPath !== 'string' || req.query.projectPath.trim().length === 0)) {
+                    return res.status(400).json({ error: 'projectPath required for project conversations' });
+                }
+                const bucketKey = scope ? (0, conversation_store_1.conversationScopeKey)(scope, '') : ensureDirectoryPath(req.query.projectPath);
+                const dir = this.conversationStore.attachmentsDirFor(bucketKey, req.params.conversationId);
+                const metadata = JSON.parse(fs_1.default.readFileSync((0, attachment_store_1.safeAttachmentMetaPath)(dir, req.params.attachmentId), 'utf8'));
+                const bytes = fs_1.default.readFileSync(path_1.default.join(dir, metadata.diskFilename));
+                res.setHeader('Content-Type', metadata.mimeType);
+                res.setHeader('Cache-Control', 'private, max-age=31536000, immutable');
+                res.setHeader('Content-Disposition', `inline; filename="${encodeURIComponent(metadata.filename)}"`);
+                return res.send(bytes);
+            }
+            catch {
+                return res.status(404).json({ error: 'Attachment not found.' });
+            }
+        });
         // Issue #1065: conversation search. Served by the existing loopback listener (C6) — no new
         // endpoint surface, no new trust boundary. Reads only the bucket index (header facts) and the
         // searchable projection (thread text); never a conversation body, which is where the raw host
@@ -6655,6 +6767,15 @@ class AiHubServer {
                 });
                 if (!continuity.ok)
                     return res.status(continuity.status).json(continuity.body);
+                // Issue #1651 R7/R8: attachments staged before the first message of a brand-new
+                // conversation. Requires the client to have already generated/supplied a
+                // conversationId (StartRunBody.conversationId already exists for this reason).
+                if (Array.isArray(req.body.attachmentIds) && req.body.attachmentIds.length > 0 && !requestedConversationId) {
+                    return res.status(400).json({ error: 'conversationId is required to attach files.' });
+                }
+                const { attachments: startAttachments, referenceSuffix: startAttachmentSuffix } = requestedConversationId
+                    ? this.resolveMessageAttachments((0, conversation_store_1.conversationScopeKey)(scope, projectPath), requestedConversationId, req.body.attachmentIds)
+                    : { attachments: undefined, referenceSuffix: '' };
                 const run = {
                     id: (0, crypto_1.randomUUID)(),
                     conversationId: requestedConversationId,
@@ -6669,7 +6790,7 @@ class AiHubServer {
                     status: 'running',
                     createdAt: startTimestamp,
                     updatedAt: startTimestamp,
-                    messages: [(0, hosts_1.createHubMessage)('manager', managerDisplay)],
+                    messages: [(0, hosts_1.createHubMessage)('manager', managerDisplay, undefined, startAttachments)],
                     events: [(0, hosts_1.createHubEvent)('system', `Starting ${configuredAgent.label} (${hostId}) in ${projectPath}`)],
                     // Issue #347 — seed phase + totals state on creation.
                     currentPhase: null,
@@ -6735,7 +6856,7 @@ class AiHubServer {
                     this.runRegistry.create(directRun, {});
                     this.scheduleRunConversationPersistence(directRun, directRun.id);
                 }
-                const child = this.hostRuntime.startRun(hostId, projectPath, message, {
+                const child = this.hostRuntime.startRun(hostId, projectPath, message + startAttachmentSuffix, {
                     onEvent: (event, channel) => {
                         this.runRegistry.update(run.id, (current) => {
                             if (event.sessionId) {
@@ -6919,9 +7040,13 @@ class AiHubServer {
                         ? this.prepareContinueMessage(run, '', coachingJobId)
                         : { message: (req.body.message || '').trim(), display: (req.body.message || '').trim() };
                 const message = prepared.message;
-                if (!message) {
+                const hasAttachments = Array.isArray(req.body.attachmentIds) && req.body.attachmentIds.length > 0;
+                if (!message && !hasAttachments) {
                     return res.status(400).json({ error: 'Coach your employee before sending the next turn.' });
                 }
+                // Issue #1651 R7/R12: resolve staged attachments into persisted metadata
+                // (attached to the manager's message) and a host-bound reference suffix.
+                const { attachments, referenceSuffix: attachmentSuffix } = this.resolveMessageAttachments((0, conversation_store_1.conversationScopeKey)(run.scope, run.projectPath), run.conversationId || run.id, req.body.attachmentIds);
                 // No resumable session — start fresh using a handoff prompt so the agent
                 // picks up from the preserved conversation state + manager coaching.
                 const reviewApprovalSystemEventText = buildReviewApprovalSystemEventText(prepared.display || message);
@@ -6945,7 +7070,7 @@ class AiHubServer {
                         // to failed/stopped by the stale flag from the original stop.
                         current.stoppedByUser = false;
                         current.sessionId = undefined;
-                        const managerMessage = (0, hosts_1.createHubMessage)('manager', prepared.display || message);
+                        const managerMessage = (0, hosts_1.createHubMessage)('manager', prepared.display || message, undefined, attachments);
                         current.messages.push(managerMessage);
                         appendDeliveredManagerMicroEvent(current, managerMessage);
                         if (reviewApprovalSystemEventText)
@@ -6969,7 +7094,7 @@ class AiHubServer {
                         this.persistRunConversation(startedFresh, startedFresh.conversationId || startedFresh.id);
                     this.runRegistry.create(run, {});
                     const freshLaunch = this.resolveLaunchAgent(run.configuredAgentId, run.hostId);
-                    const freshChild = this.hostRuntime.startRun(run.hostId, run.projectPath, freshPayload.message, {
+                    const freshChild = this.hostRuntime.startRun(run.hostId, run.projectPath, freshPayload.message + attachmentSuffix, {
                         onEvent: (event, channel) => {
                             this.runRegistry.update(run.id, (current) => {
                                 if (event.sessionId) {
@@ -7021,7 +7146,7 @@ class AiHubServer {
                     // to failed/stopped by the stale flag from the original stop.
                     current.stoppedByUser = false;
                     // #521: bubble shows the manager's words; the agent gets the full message.
-                    const managerMessage = (0, hosts_1.createHubMessage)('manager', prepared.display || message, deliveryStatus);
+                    const managerMessage = (0, hosts_1.createHubMessage)('manager', prepared.display || message, deliveryStatus, attachments);
                     current.messages.push(managerMessage);
                     appendDeliveredManagerMicroEvent(current, managerMessage);
                     if (reviewApprovalSystemEventText)
@@ -7054,7 +7179,7 @@ class AiHubServer {
                 // them, so any other continueRun call site delivering the turn (or a
                 // turn that exits before its first event) left the badge stuck
                 // forever. See clearStaleDeliveryStatuses and handleRunExit.
-                const child = this.hostRuntime.continueRun(run.hostId, run.projectPath, run.sessionId, message, {
+                const child = this.hostRuntime.continueRun(run.hostId, run.projectPath, run.sessionId, message + attachmentSuffix, {
                     onEvent: (event, channel) => {
                         if (run.hostId === 'codex' && reviewApprovalSystemEventText) {
                             codexMissingReasoningResumeError = codexMissingReasoningResumeError ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.315",
+  "version": "2.0.316",
   "description": "FRAIM Hub local companion package.",
   "author": "Sid Mathur <sid.mathur@gmail.com>",
   "homepage": "https://github.com/mathursrus/FRAIM#readme",
@@ -211,7 +211,7 @@
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
     "extract-zip": "^2.0.1",
-    "fraim": "2.0.315",
+    "fraim": "2.0.316",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",
@@ -220,6 +220,7 @@
     "resend": "^6.9.3",
     "selfsigned": "^5.5.0",
     "semver": "^7.7.4",
+    "sharp": "^0.34.5",
     "stripe": "^20.3.1",
     "tar": "^7.4.3",
     "toml": "^3.0.0",

package/public/ai-hub/index.html

@@ -499,7 +499,10 @@
                 </span>
               </summary>
               <div class="panel-body">
-                <div class="coach">
+                <div class="coach" id="coach">
+                  <!-- Issue #1651: dashed overlay shown only while a drag is over .coach
+                       (toggled via the coach.drag-active class in script.js). -->
+                  <div class="composer-dropzone" id="composer-dropzone">Drop to attach</div>
                   <!-- Issue #512 R7.7: review actions live in the SAME bar as the
                        coaching chips. Hidden until a deliverable is awaiting review;
                        the coaching chips below never disappear. -->
@@ -589,10 +592,16 @@
                     <button class="delivery-option delivery-option--redirect" type="button" id="delivery-redirect" aria-pressed="false">Redirect now</button>
                   </div>
                   <p class="delivery-help" id="delivery-help" hidden></p>
+                  <!-- Issue #1651: staged attachment chips (thumbnail/file icon, filename,
+                       size, remove control), rendered before Send by renderStagedAttachments(). -->
+                  <div class="staged-attachments" id="staged-attachments"></div>
                   <div class="coach-input">
-                    <textarea id="coach-text" aria-label="Coach the employee" placeholder="Tell the employee what to do next..."></textarea>
+                    <button class="attach-btn" type="button" id="attach-btn" aria-label="Attach a file or screenshot" title="Attach a file or screenshot">&#128206;</button>
+                    <input type="file" id="attach-file-input" multiple accept="image/png,image/jpeg,image/gif,.pdf,.txt,.log" hidden>
+                    <textarea id="coach-text" aria-label="Coach the employee" placeholder="Tell the employee what to do next... (paste a screenshot with Ctrl+V)"></textarea>
                     <button class="send-button" type="button" id="send" aria-label="Send coaching message" title="Send coaching message" disabled>↑</button>
                   </div>
+                  <div class="composer-hint">Attach or paste a screenshot, log, or PDF, up to 10&nbsp;MB each.</div>
                   <div class="coach-note" id="coach-note"></div>
                 </div>
               </div>

package/public/ai-hub/script.js

@@ -100,6 +100,11 @@ const state = {
   brandEditorStatusWarn: false,
   // Issue #540 R10: pending run params captured when hire strip is shown.
   _hireStripPending: null,
+  // Issue #1651: files/screenshots staged in the composer before Send.
+  // { localId, file, dataUrl (images only), error }. Scoped to the active
+  // conversation the same way pendingCoachingJobId is: cleared on send and on
+  // conversation switch (see clearStagedAttachments and the switch handler).
+  stagedAttachments: [],
 };
 
 const bootstrapCache = new Map();
@@ -122,6 +127,8 @@ function gatherElements() {
     'messages',
     'coach-text', 'send', 'micro-manage', 'micro-log', 'resume-command', 'resume-command-code', 'resume-command-copy',
     'status-line', 'coach-note',
+    // Issue #1651: composer attachments.
+    'coach', 'composer-dropzone', 'staged-attachments', 'attach-btn', 'attach-file-input',
     // Issue #1176: continue-run delivery control.
     'delivery-control', 'delivery-after', 'delivery-redirect', 'delivery-help',
     'coach-panel', 'coach-summary',
@@ -1866,6 +1873,16 @@ function conversationStartTimestamp(conv) {
   return timestampMillis(conv.createdAt) || conversationTimestamp(conv);
 }
 
+// Stable kickoff-time comparator for ordering runs by when they were kicked off, not by
+// their last activity. Shared by the Projects rail (renderRail's activeConvs/doneConvs
+// sort) and the Manager/Company rail (tfAreaScopedConversations) so "In Progress"
+// ordering is identical across all three tabs (#1652). Sorting by lastUpdatedAt instead
+// reshuffles the list on every update a run receives; createdAt pins a run where it was
+// kicked off and never changes again.
+function compareByKickoffTime(a, b) {
+  return conversationStartTimestamp(b) - conversationStartTimestamp(a) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+
 function timestampMillis(value) {
   if (typeof value === 'number' && Number.isFinite(value) && value > 0) return value;
   if (typeof value === 'string') {
@@ -2726,8 +2743,8 @@ function renderRail() {
     }
   }
   // Latest kickoff first within each section.
-  activeConvs.sort((a, b) => convStart(b) - convStart(a) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-  doneConvs.sort((a, b) => convStart(b) - convStart(a) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  activeConvs.sort(compareByKickoffTime);
+  doneConvs.sort(compareByKickoffTime);
 
   // Build per-employee groups for completed runs.
   // Completed runs with a personaKey group under that employee; completed runs
@@ -3896,6 +3913,9 @@ function renderActive() {
     // A pending coaching job is scoped to the active conversation — discard it
     // whenever the user switches to a different conversation.
     clearPendingCoachingJob();
+    // Issue #1651: staged attachments are equally scoped to the active
+    // conversation — a switch must not carry them into a different thread.
+    clearStagedAttachments();
     // Issue #1176 R40: the delivery control resets to "After current" whenever
     // the active conversation changes, so a prior urgent choice can't redirect
     // a different conversation's next guidance.
@@ -5556,6 +5576,29 @@ function appendMessageDom(role, text, conv, message) {
     article.appendChild(raw);
   }
   article.appendChild(bubble);
+  // Issue #1651 R13: one chip per persisted attachment — thumbnail for images
+  // (byte-served by GET .../attachments/:id), a generic file glyph otherwise.
+  if (message && Array.isArray(message.attachments)) {
+    message.attachments.forEach((att) => {
+      const chip = document.createElement('span');
+      chip.className = 'msg-attachment';
+      const thumb = document.createElement('span');
+      thumb.className = 'thumb';
+      if (att.mimeType && att.mimeType.startsWith('image/')) {
+        const img = document.createElement('img');
+        img.src = attachmentUrlFor(conv, att.id);
+        img.alt = att.filename;
+        thumb.appendChild(img);
+      } else {
+        thumb.textContent = '\u{1F4C4}'; // 📄
+      }
+      const label = document.createElement('span');
+      label.textContent = `${att.filename} (${formatAttachmentSize(att.sizeBytes)})`;
+      chip.appendChild(thumb);
+      chip.appendChild(label);
+      article.appendChild(chip);
+    });
+  }
   els['messages'].appendChild(article);
 }
 
@@ -5782,6 +5825,160 @@ function scrollThreadForReview(conv) {
   host.scrollTop = desiredTop;
 }
 
+// ---------------------------------------------------------------------------
+// Issue #1651: composer attachments (attach button, paste, drag-drop, upload)
+// ---------------------------------------------------------------------------
+
+const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+const MAX_ATTACHMENTS_PER_SEND = 5;
+const ACCEPTED_ATTACHMENT_MIME_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'application/pdf', 'text/plain']);
+let stagedAttachmentSeq = 0;
+
+function formatAttachmentSize(bytes) {
+  if (bytes < 1024) return bytes + ' B';
+  if (bytes < 1024 * 1024) return Math.round(bytes / 1024) + ' KB';
+  return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+}
+
+function hasValidStagedAttachment() {
+  return state.stagedAttachments.some((a) => !a.error);
+}
+
+function renderStagedAttachments() {
+  const row = els['staged-attachments'];
+  if (!row) return;
+  row.innerHTML = '';
+  state.stagedAttachments.forEach((item) => {
+    const chip = document.createElement('div');
+    chip.className = 'attachment-chip' + (item.error ? ' chip-error' : '');
+
+    const thumb = document.createElement('span');
+    thumb.className = 'thumb';
+    if (item.dataUrl) {
+      const img = document.createElement('img');
+      img.src = item.dataUrl;
+      img.alt = '';
+      thumb.appendChild(img);
+    } else {
+      thumb.textContent = '\u{1F4C4}'; // 📄
+    }
+
+    const meta = document.createElement('span');
+    meta.className = 'meta';
+    const fname = document.createElement('span');
+    fname.className = 'fname';
+    fname.textContent = item.file.name;
+    meta.appendChild(fname);
+    meta.appendChild(document.createElement('br'));
+    if (item.error) {
+      const err = document.createElement('span');
+      err.className = 'chip-error-text';
+      err.textContent = item.error;
+      meta.appendChild(err);
+    } else {
+      const size = document.createElement('span');
+      size.className = 'fsize';
+      size.textContent = formatAttachmentSize(item.file.size);
+      meta.appendChild(size);
+    }
+
+    const remove = document.createElement('button');
+    remove.className = 'chip-remove';
+    remove.type = 'button';
+    remove.setAttribute('aria-label', `Remove ${item.file.name}`);
+    remove.textContent = '×'; // ×
+    remove.addEventListener('click', () => {
+      state.stagedAttachments = state.stagedAttachments.filter((a) => a.localId !== item.localId);
+      renderStagedAttachments();
+      syncSendButton();
+    });
+
+    chip.appendChild(thumb);
+    chip.appendChild(meta);
+    chip.appendChild(remove);
+    row.appendChild(chip);
+  });
+}
+
+function clearStagedAttachments() {
+  state.stagedAttachments = [];
+  renderStagedAttachments();
+}
+
+// R5: an oversized or unsupported file stages as a visually distinct error
+// chip and is excluded from send; R4: everything else stages with a
+// thumbnail (images, via FileReader) or a generic file icon.
+function stageAttachmentFile(file) {
+  if (!file || state.stagedAttachments.length >= MAX_ATTACHMENTS_PER_SEND) return;
+  const localId = 'att-' + (stagedAttachmentSeq += 1);
+  if (file.size > MAX_ATTACHMENT_BYTES) {
+    state.stagedAttachments.push({ localId, file, dataUrl: null, error: `Over ${MAX_ATTACHMENT_BYTES / (1024 * 1024)} MB limit, not attached` });
+    renderStagedAttachments();
+    syncSendButton();
+    return;
+  }
+  if (!ACCEPTED_ATTACHMENT_MIME_TYPES.has(file.type)) {
+    state.stagedAttachments.push({ localId, file, dataUrl: null, error: 'Unsupported file type, not attached' });
+    renderStagedAttachments();
+    syncSendButton();
+    return;
+  }
+  if (file.type.startsWith('image/')) {
+    const reader = new FileReader();
+    reader.onload = () => {
+      state.stagedAttachments.push({ localId, file, dataUrl: reader.result, error: null });
+      renderStagedAttachments();
+      syncSendButton();
+    };
+    reader.readAsDataURL(file);
+  } else {
+    state.stagedAttachments.push({ localId, file, dataUrl: null, error: null });
+    renderStagedAttachments();
+    syncSendButton();
+  }
+}
+
+// R7: upload every valid staged file to the per-conversation attachment
+// endpoint, returning the ids the subsequent message-send call references.
+async function uploadStagedAttachments(conv) {
+  const valid = state.stagedAttachments.filter((a) => !a.error);
+  if (valid.length === 0) return [];
+  const scope = convScope(conv);
+  const params = new URLSearchParams();
+  if (scope === 'manager' || scope === 'company') {
+    params.set('scope', scope);
+  } else {
+    params.set('projectPath', (conv && conv.projectPath) || state.projectPath || '');
+  }
+  const url = `/api/ai-hub/conversations/${encodeURIComponent(conv.id)}/attachments?${params.toString()}`;
+  const ids = [];
+  for (const item of valid) {
+    const result = await requestJson(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': item.file.type || 'application/octet-stream',
+        'X-Attachment-Filename': encodeURIComponent(item.file.name),
+      },
+      body: item.file,
+    });
+    if (result && result.id) ids.push(result.id);
+  }
+  return ids;
+}
+
+// R13: URL the transcript renderer points an <img> (or download affordance)
+// at for one persisted attachment.
+function attachmentUrlFor(conv, attachmentId) {
+  const scope = convScope(conv);
+  const params = new URLSearchParams();
+  if (scope === 'manager' || scope === 'company') {
+    params.set('scope', scope);
+  } else {
+    params.set('projectPath', (conv && conv.projectPath) || state.projectPath || '');
+  }
+  return `/api/ai-hub/conversations/${encodeURIComponent(conv.id)}/attachments/${encodeURIComponent(attachmentId)}?${params.toString()}`;
+}
+
 function syncSendButton() {
   const conv = activeConversation();
   const hasText = els['coach-text'].value.trim().length > 0;
@@ -5801,7 +5998,9 @@ function syncSendButton() {
   // is enough to enable Send even with an empty textarea — the user just
   // wants to fire that coaching directive, optionally with added context.
   const hasPendingJob = !!state.pendingCoachingJobId;
-  els['send'].disabled = !((hasText || hasPendingJob) && (resumable || canRestartWithCoaching));
+  // Issue #1651 R6: a valid staged attachment is enough to enable Send even
+  // with an empty textarea, same as a pending coaching job.
+  els['send'].disabled = !((hasText || hasPendingJob || hasValidStagedAttachment()) && (resumable || canRestartWithCoaching));
 }
 
 function defaultCoachNote(conv) {
@@ -8745,6 +8944,9 @@ async function continueRun(text, options) {
   // Issue #1176: 'stop' course-corrects the active turn instead of queueing
   // behind it; omitted/'after' is the default queue-after-current behavior.
   const deliveryIntent = opts.deliveryIntent === 'stop' ? 'stop' : undefined;
+  // Issue #1651 R7: ids already uploaded via uploadStagedAttachments(), resolved
+  // server-side into AiHubMessage.attachments plus a host-bound reference.
+  const attachmentIds = Array.isArray(opts.attachmentIds) && opts.attachmentIds.length > 0 ? opts.attachmentIds : undefined;
   if (!opts.preserveReviewApproved) {
     conv.reviewApproved = false;
     conv.pendingDeliveryActionId = null;
@@ -8771,7 +8973,13 @@ async function continueRun(text, options) {
       run = await requestJson(`/api/ai-hub/runs/${conv.runId}/messages`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ instructions: effectiveText, ...(coachingJobId ? { coachingJobId } : {}), ...(deliveryIntent ? { deliveryIntent } : {}), ...(opts.selectedReviewAction ? { selectedReviewAction: opts.selectedReviewAction } : {}) }),
+        body: JSON.stringify({
+          instructions: effectiveText,
+          ...(coachingJobId ? { coachingJobId } : {}),
+          ...(deliveryIntent ? { deliveryIntent } : {}),
+          ...(opts.selectedReviewAction ? { selectedReviewAction: opts.selectedReviewAction } : {}),
+          ...(attachmentIds ? { attachmentIds } : {}),
+        }),
       });
     } catch (e) {
       const isNotFound = /not found/i.test((e && e.message) || '');
@@ -8821,6 +9029,7 @@ async function continueRun(text, options) {
             instructions: effectiveText,
             ...(coachingJobId ? { coachingJobId } : {}),
             ...(opts.selectedReviewAction ? { selectedReviewAction: opts.selectedReviewAction } : {}),
+            ...(attachmentIds ? { attachmentIds } : {}),
           }),
         });
         conv.runId = run.id; // bind the conversation to the new run
@@ -8921,6 +9130,9 @@ function foldRunIntoConversation(conv, run) {
     if (typeof m.createdAt === 'string') record.createdAt = m.createdAt;
     // Issue #1176: carry the submit-time queued/redirecting badge, if any.
     if (m.deliveryStatus) record.deliveryStatus = m.deliveryStatus;
+    // Issue #1651: carry attachment metadata, or a reloaded/re-folded conversation
+    // silently loses its attachment chips even though the blobs remain on disk.
+    if (Array.isArray(m.attachments) && m.attachments.length > 0) record.attachments = m.attachments;
     const parsed = timestampMillis(m.createdAt);
     if (parsed) record.at = parsed;
     return record;
@@ -10094,9 +10306,10 @@ function wireEvents() {
   }
   els['send'].addEventListener('click', async () => {
     const text = els['coach-text'].value.trim();
-    // Allow send when textarea is empty IFF a coaching job is pending — the
-    // user clicked a quick-coach button and just wants to fire that job.
-    if (!text && !state.pendingCoachingJobId) return;
+    // Allow send when textarea is empty IFF a coaching job is pending, or a
+    // valid attachment is staged (#1651 R6) — the user just wants to fire
+    // that job, or hand over the attachment(s), with no accompanying text.
+    if (!text && !state.pendingCoachingJobId && !hasValidStagedAttachment()) return;
     els['coach-text'].value = '';
     syncSendButton();
     const conv = activeConversation();
@@ -10115,11 +10328,26 @@ function wireEvents() {
     const chosenAgent = normalizeActiveAgentId(
       els['active-employee-select'] && els['active-employee-select'].value
     );
+    // Issue #1651 R7: upload any staged attachments before the message send so
+    // the ids can ride along on the same request. Uploading is a no-op when
+    // nothing valid is staged.
+    let attachmentIds = [];
+    if (conv && hasValidStagedAttachment()) {
+      try {
+        attachmentIds = await uploadStagedAttachments(conv);
+      } catch (error) {
+        showStatus(error.message, true);
+      }
+    }
+    clearStagedAttachments();
     if (conv && chosenAgent && chosenAgent !== normalizeActiveAgentId(conversationAgentName(conv))) {
+      // Known limitation: an agent switch on the same send that carries
+      // attachments uploads the files (they land on disk) but does not yet
+      // thread attachmentIds through restartConvWithAgent's fresh-run message.
       state.selectedEmployeeId = chosenAgent;
       await restartConvWithAgent(conv, chosenAgent, text);
     } else {
-      await continueRun(text, { deliveryIntent });
+      await continueRun(text, { deliveryIntent, attachmentIds });
     }
   });
 
@@ -10133,6 +10361,50 @@ function wireEvents() {
     });
   }
 
+  // Issue #1651 R1/R2/R3: attach button (file picker), drag-drop onto the
+  // composer, and paste-image support — ported from the validated mock
+  // (docs/feature-specs/mocks/1651-view.html).
+  if (els['attach-btn'] && els['attach-file-input']) {
+    els['attach-btn'].addEventListener('click', () => els['attach-file-input'].click());
+    els['attach-file-input'].addEventListener('change', () => {
+      Array.from(els['attach-file-input'].files || []).forEach(stageAttachmentFile);
+      els['attach-file-input'].value = '';
+    });
+  }
+  if (els['coach']) {
+    ['dragenter', 'dragover'].forEach((evt) => {
+      els['coach'].addEventListener(evt, (e) => {
+        e.preventDefault();
+        els['coach'].classList.add('drag-active');
+      });
+    });
+    ['dragleave', 'drop'].forEach((evt) => {
+      els['coach'].addEventListener(evt, (e) => {
+        e.preventDefault();
+        els['coach'].classList.remove('drag-active');
+      });
+    });
+    els['coach'].addEventListener('drop', (e) => {
+      Array.from((e.dataTransfer && e.dataTransfer.files) || []).forEach(stageAttachmentFile);
+    });
+  }
+  if (els['coach-text']) {
+    els['coach-text'].addEventListener('paste', (e) => {
+      const items = (e.clipboardData && e.clipboardData.items) || [];
+      Array.from(items).forEach((item) => {
+        if (!item.type || !item.type.startsWith('image/')) return;
+        const file = item.getAsFile();
+        if (!file) return;
+        try {
+          Object.defineProperty(file, 'name', { value: 'pasted-screenshot.png' });
+        } catch {
+          /* some browsers disallow redefining File.name; stage it under its own name */
+        }
+        stageAttachmentFile(file);
+      });
+    });
+  }
+
   // Issue #442: keep A/B toggle visible only when the selected employee supports
   // direct-path invocation (supportsRaw). Also wire the explanation paragraph.
   if (els['employee-select']) {
@@ -14011,9 +14283,13 @@ function tfResolveAreaView(area, fallbackConv) {
 }
 
 function tfAreaScopedConversations(area) {
+  // Uses the same stable kickoff-time comparator as renderRail()'s Projects-rail sort
+  // (#1652). Sorting by lastUpdatedAt instead (as this used to) reshuffled the
+  // Manager/Company "In Progress" list on every poll tick, since lastUpdatedAt changes
+  // with every message a running job emits; createdAt pins a run where it was kicked off.
   return Object.values(state.conversations || {}).flat()
     .filter((conv) => conv && convScope(conv) === area)
-    .sort((a, b) => (b.lastUpdatedAt || 0) - (a.lastUpdatedAt || 0));
+    .sort(compareByKickoffTime);
 }
 
 // Every area has FRAIMworker. Named employees join an area when that area is

package/public/ai-hub/styles.css

@@ -1987,6 +1987,8 @@ img.coach-employee-avatar { object-fit: cover; border-radius: 4px; }
   border: none;
   border-radius: 0;
   padding: 0;
+  /* Issue #1651: anchors the drag-over dropzone overlay. */
+  position: relative;
 }
 /* Send button embedded inside the textarea wrapper */
 .coach-input {
@@ -1999,7 +2001,7 @@ img.coach-employee-avatar { object-fit: cover; border-radius: 4px; }
   resize: vertical;
   border: 1px solid var(--line);
   border-radius: 8px;
-  padding: 12px 52px 12px 14px;
+  padding: 12px 52px 12px 44px;
   font: inherit;
   color: var(--text);
   background: var(--surface);
@@ -2022,6 +2024,122 @@ img.coach-employee-avatar { object-fit: cover; border-radius: 4px; }
   justify-content: center;
   border: none;
 }
+
+/* Issue #1651: attach button sits to the left inside the same textarea
+   wrapper, sized to match #send (32x32, 6px radius). */
+.attach-btn {
+  position: absolute;
+  bottom: 7px;
+  left: 7px;
+  width: 32px;
+  height: 32px;
+  padding: 0;
+  border-radius: 6px;
+  border: 1px solid var(--line);
+  background: var(--surface);
+  color: var(--muted);
+  font-size: 15px;
+  line-height: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+}
+.attach-btn:hover { background: var(--soft); color: var(--text); }
+.attach-btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+/* Staged attachments: chips shown above the composer before send. Thumbnail
+   sizing/radius matches .brand-logo-drop .blp; remove control matches
+   .srch-clear (bare glyph button). */
+.staged-attachments {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-bottom: 8px;
+}
+.staged-attachments:empty { display: none; }
+.attachment-chip {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  max-width: 220px;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  background: var(--surface);
+  box-shadow: var(--shadow);
+  padding: 6px 28px 6px 6px;
+}
+.attachment-chip .thumb {
+  width: 36px;
+  height: 36px;
+  border-radius: 8px;
+  box-shadow: 0 0 0 1px var(--line);
+  flex-shrink: 0;
+  overflow: hidden;
+  background: var(--soft);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 15px;
+}
+.attachment-chip .thumb img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.attachment-chip .meta { min-width: 0; }
+.attachment-chip .fname { font-size: 12px; font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 140px; display: block; }
+.attachment-chip .fsize { font-size: 11px; color: var(--muted); }
+.attachment-chip .chip-remove {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  border: none;
+  background: none;
+  color: var(--muted);
+  cursor: pointer;
+  font-size: 15px;
+  line-height: 1;
+  padding: 2px;
+}
+.attachment-chip .chip-remove:hover { color: var(--danger); }
+.attachment-chip.chip-error { border-color: var(--danger); }
+.attachment-chip .chip-error-text { font-size: 10.5px; color: var(--danger); }
+
+/* Drag-over state: dashed accent overlay across the whole coach block, same
+   visual language as .brand-logo-drop. */
+.composer-dropzone {
+  position: absolute;
+  inset: -6px;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  border: 1px dashed color-mix(in srgb, var(--accent) 55%, var(--line));
+  border-radius: 12px;
+  background: var(--accent-soft);
+  color: var(--accent);
+  font-size: 12.5px;
+  font-weight: 650;
+  z-index: 3;
+  pointer-events: none;
+}
+.coach.drag-active .composer-dropzone { display: flex; }
+
+/* Attachment rendered inline inside a sent transcript message (appendMessageDom). */
+.msg-attachment {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  margin-top: 6px;
+  margin-right: 6px;
+  padding: 5px 8px 5px 5px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--surface);
+  font-size: 11.5px;
+  color: var(--text);
+}
+.msg-attachment .thumb { width: 26px; height: 26px; border-radius: 6px; overflow: hidden; background: var(--soft); flex-shrink: 0; display: flex; align-items: center; justify-content: center; }
+.msg-attachment .thumb img { width: 100%; height: 100%; object-fit: cover; display: block; }
+
+.composer-hint { font-size: 11px; color: var(--muted); margin-top: 6px; }
 .coach-note {
   margin-top: 6px;
   color: var(--muted);