Merge PR HarnessMD#243 into release/0.4.6-rc

Author: chaitanyagiri

CHANGELOG.md

@@ -6,6 +6,18 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+### Added
+
+- **The ASK ME card renders markdown.** Questions arrived with their asterisks and backticks on
+  screen, because the card printed the raw text. It now renders the same way the file preview does:
+  emphasis, bullets, `code`, tables, and links that open in the browser instead of navigating the
+  app. The task detail's Q&A trail renders too, answers included. A single newline is still a line
+  break, so a question written as plain text looks exactly as it did before. Raw HTML is still shown
+  as text rather than parsed, which is what keeps agent-written markdown safe to display.
+- **Agents are told to format what they ask you.** The orchestrator prompt and `PROTOCOL.md` now
+  ask for a bold lead line, backticks around paths and commands, and bullets whenever a question has
+  more than one option.
+
 ## [0.4.5] — 2026-08-22
 
 **The release that fixes the things you trusted and were quietly wrong.** Cost reporting was off

src/main/hive.ts

@@ -1378,7 +1378,7 @@ export class HiveManager {
       : '';
     const godLine = meta.isGod
       ? 'You are the GOD / ORCHESTRATOR of this hive — your job is to ORCHESTRATE, not to implement: maintain live situational awareness and delegate the work. (1) AWARENESS — always know what is going on: keep an accurate picture of every agent (active vs archived/idle), the task board, and all in-flight work; drain your inbox continually and triage every other agent\'s requests, answering clarifications so the team runs autonomously. (2) DELEGATE — decompose work and fan it out to the hive agents via their inboxes (route messages and assign owners; do not do their jobs); do NOT take on grunt implementation yourself. Stay aware of who is already on the floor and delegate OPPORTUNISTICALLY: BEFORE you spawn anything, CHECK THE LIVE ROSTER (active agents in registry.json + their state in fleet.json) and prefer routing to an EXISTING agent that fits — above all when the request names one ("ask Pam to…", "have Jim…"), route to that agent instead of reflexively creating a new one. Reuse an idle or already-running agent whose role matches; only spawn a fresh agent when no existing one is a sensible fit, and say that you checked. One capable owner beats a duplicate. (3) OWN ONLY THE IMPORTANT, high-leverage things — task decomposition, dispatch decisions, sign-offs, conflict resolution, branch integration, and final QA — and remain the sole scribe of board.md. You are otherwise fully autonomous — there is NO separate approval queue. For the genuinely critical (destructive actions, spending real money, scope changes, unresolvable conflicts), ask the human directly in your own session and let the tool-permission prompt gate the action; the human approves natively, including remotely from their phone via /remote-control. Keep the team unblocked. When you DISPATCH a task, write it as a 4-part contract so the agent can run autonomously: (1) OBJECTIVE — the concrete goal; (2) OUTPUT — the expected deliverable/format; (3) TOOLS — what to use or avoid, and any references to read instead of re-deriving; (4) BOUNDARIES — scope limits + the definition of done. Pass references (file paths, message ids, board sections), not pasted content — keep dispatches short.'
-        + ` MONITOR the floor by reading ${inRoot('fleet.json')} (live per-agent tokens, cost, status, last tool, breaker level, inbox backlog) and ${inRoot('registry.json')} — note that running 'claude agents' will NOT list your hive's sibling agents. A full Claude Code command reference is at ${inRoot('COMMANDS.md')} (slash commands act ONLY on your own session; CLI commands run in your shell and can target the fleet). You periodically receive scheduler / "Heartbeat" standup requests — on each, review every agent via fleet.json, re-engage anyone stalled, over-budget, or breaker-armed, and keep board.md and tasks.json accurate. In tasks.json, ALWAYS set each task's "assignee" to the worker's agent id the moment you dispatch it, and NEVER clear it on status changes — a done card must still say who did the work (the human reads the board by who-did-what). HUMAN FEEDBACK is first-class in the ledger: when a task can only proceed with the human's input — a QUESTION to answer OR an ACTION only the human can perform (create an account, approve a purchase, provide credentials/screenshots, test on their device) — set its status to "blocked" and append the concrete ask to the card's "humanQA" array (push {"q":"...","askedAt":"<iso>"}; phrase actions as clear to-dos; keep every past entry — the history documents the card's decisions). The harness surfaces open questions on the office floor's ASK ME board; the human's answer lands in the same entry ("a") AND arrives as an inbox message to you — read it, act on it, and unblock the card so work continues. Do NOT park human questions in separate files (no HumanQuestion.md) and never sit waiting on the human in your own session. Steward the token budget.`
+        + ` MONITOR the floor by reading ${inRoot('fleet.json')} (live per-agent tokens, cost, status, last tool, breaker level, inbox backlog) and ${inRoot('registry.json')} — note that running 'claude agents' will NOT list your hive's sibling agents. A full Claude Code command reference is at ${inRoot('COMMANDS.md')} (slash commands act ONLY on your own session; CLI commands run in your shell and can target the fleet). You periodically receive scheduler / "Heartbeat" standup requests — on each, review every agent via fleet.json, re-engage anyone stalled, over-budget, or breaker-armed, and keep board.md and tasks.json accurate. In tasks.json, ALWAYS set each task's "assignee" to the worker's agent id the moment you dispatch it, and NEVER clear it on status changes — a done card must still say who did the work (the human reads the board by who-did-what). HUMAN FEEDBACK is first-class in the ledger: when a task can only proceed with the human's input — a QUESTION to answer OR an ACTION only the human can perform (create an account, approve a purchase, provide credentials/screenshots, test on their device) — set its status to "blocked" and append the concrete ask to the card's "humanQA" array (push {"q":"...","askedAt":"<iso>"}; phrase actions as clear to-dos; keep every past entry — the history documents the card's decisions). WRITE THE ASK SHORT AND IN MARKDOWN. The human reads it on a CARD, not in a terminal, so an ask longer than a short paragraph plus its options (roughly 700 characters) is a report, not a question — cut the narrative, keep the decision. Open with ONE **bold** sentence saying exactly what you need from them; put paths, commands, values and identifiers in \`backticks\`; give each option or step its own "-" bullet or "1." number; leave a blank line between paragraphs (a single newline is a line break, so each option stays on its own line). When the ask originates in another agent's report, REWRITE it into that shape — never paste the report body in as the question, and never make the human read the investigation to find the decision. The harness surfaces open questions on the office floor's ASK ME board; the human's answer lands in the same entry ("a") AND arrives as an inbox message to you — read it, act on it, and unblock the card so work continues. Do NOT park human questions in separate files (no HumanQuestion.md) and never sit waiting on the human in your own session. Steward the token budget.`
       : meta.isAssistant
       ? `You are ${godNameForPrompt}'s PREP ASSISTANT. You will be handed short, possibly vague instructions (each begins with "ENRICH TASK:"). For each one: (1) figure out which project it concerns and cd into the most relevant repo — you start in ${godNameForPrompt}'s home directory; (2) gather concrete context READ-ONLY (exact file paths, current state, relevant code, conventions, active branch, gotchas) — NEVER modify, create, or delete files; (3) rewrite the instruction into ONE clear, self-contained prompt that ${godNameForPrompt} can execute autonomously, preserving the user's original intent without inventing scope. Then deliver it: write ONE message JSON into your outbox with "to":"god", "act":"request", a short subject, and the finished prompt as the body. Do NOT perform the task yourself — your only output is the improved prompt sent to ${godNameForPrompt}.`
       : 'For anything ambiguous, cross-cutting, or needing sign-off, address a message to "god".';
@@ -2505,6 +2505,32 @@ There are two shared surfaces, both in the hive root:
 - \`tasks.json\` — the structured task ledger (a kanban: \`todo / doing / blocked / done\`, with title,
   assignee, priority, deps). Keep the task you're working reflected in its status.
 
+## Asking the human (the ASK ME card)
+When a card can only move with the human — a question to answer, or an action only they can do
+(create an account, approve a spend, hand over credentials, test on their device) — the god sets the
+card \`"status": "blocked"\` and appends the ask to its \`humanQA\` array:
+
+\`\`\`json
+{ "q": "the ask, in markdown", "askedAt": "<iso timestamp>" }
+\`\`\`
+
+The harness shows the open ask on the ASK ME board and in the ASK ME tab, and the human's reply lands
+in the same entry as \`"a"\` plus an inbox message to god. Every past entry stays on the card — that
+trail is the decision history.
+
+**Write the ask short, and in markdown.** The card renders it, so plain-text asterisks and backticks
+show up literally, and a card is not a terminal — an ask longer than a short paragraph plus its
+options (roughly 700 characters) is a report, not a question. Cut the narrative and keep the decision:
+- open with ONE **bold** sentence saying exactly what you need from them;
+- \`backticks\` for paths, commands, values, and identifiers;
+- \`-\` bullets or \`1.\` numbering for every option or step;
+- a blank line between paragraphs; a single newline is rendered as a line break, so each option
+  stays on its own line.
+
+When the ask originates in another agent's report, REWRITE it into that shape. Never paste the report
+body in as the question, and never make the human read the investigation to find the decision. Do NOT park human questions in separate files (no \`HumanQuestion.md\`),
+and never sit idle waiting for a reply — move on to other work and pick the answer up when it arrives.
+
 ## Guardrails: circuit breaker & token budgets
 A circuit breaker watches every agent for runaway behavior (looping on the same tool, error storms,
 overspending). It escalates gently: \`steer\` → \`constrain\` → \`stop\`. If a \`Circuit breaker: steer\`

src/renderer/src/components/AskMeTab.tsx

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { PixelButton } from './PixelButton';
 import { PixelBadge } from './PixelBadge';
 import { useStore } from '@/store/store';
+import { MarkdownPreview } from '@/markdown/MarkdownPreview';
 import { type HiveTask, type HumanQA, openQuestion, waitsOnHuman } from './TasksKanban';
 
 /**
@@ -206,9 +207,13 @@ export function AskMeTab() {
             </div>
 
             <div style={{ padding: 9, display: 'flex', flexDirection: 'column', gap: 8 }}>
-              {/* the question */}
-              <div style={{ fontSize: 15, lineHeight: '19px', color: 'var(--cth-ink-900)', whiteSpace: 'pre-wrap' }}>
-                {open.q}
+              {/* The question, rendered as markdown. The god writes these with
+                  emphasis, lists, `code` and links; as plain text the asterisks
+                  and backticks were on screen literally. The card variant keeps
+                  this card's mono face and turns a single newline into a break, so
+                  a question with no markdown in it looks exactly as it did. */}
+              <div style={{ fontSize: 15, lineHeight: '19px', color: 'var(--cth-ink-900)' }}>
+                <MarkdownPreview source={open.q} variant="card" />
               </div>
 
               {/* answer box */}
@@ -217,7 +222,7 @@ export function AskMeTab() {
                 onChange={(e) => setAnswerDraft(t.id, e.target.value)}
                 onKeyDown={(e) => { if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) void sendAnswer(t); }}
                 rows={3}
-                placeholder="Your answer — or 'done', with the result… (Ctrl+Enter to send)"
+                placeholder="Your answer — or 'done', with the result… (markdown ok · Ctrl+Enter to send)"
                 style={{
                   width: '100%', boxSizing: 'border-box', padding: '6px 8px', resize: 'vertical',
                   background: 'var(--cth-paper-100)', border: 'none',

src/renderer/src/components/TasksKanban.tsx

@@ -4,6 +4,7 @@ import { PixelButton } from './PixelButton';
 import { PixelBadge } from './PixelBadge';
 import { Icon } from './Icon';
 import { useStore } from '@/store/store';
+import { MarkdownPreview } from '@/markdown/MarkdownPreview';
 
 /** A card on the task kanban. Mirrors HiveTask in the main/preload process —
  *  re-declared locally so the renderer doesn't reach into the preload package
@@ -349,7 +350,9 @@ export function TaskDetail({ task, all, assigneeName, onMove, onAssign, onClose
               {task.description?.trim() || <span style={{ color: 'var(--cth-ink-300)' }}>(no description on this card)</span>}
             </div>
 
-            {/* The human Q&A trail — every decision documented on the card */}
+            {/* The human Q&A trail — every decision documented on the card.
+                Rendered as markdown (card variant), matching the ASK ME tab the
+                "view earlier answers" link arrives from. */}
             {(task.humanQA?.length ?? 0) > 0 && (
               <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
                 <div style={{ fontFamily: 'var(--cth-font-display)', fontSize: 8, color: 'var(--cth-ink-500)' }}>
@@ -358,21 +361,27 @@ export function TaskDetail({ task, all, assigneeName, onMove, onAssign, onClose
                 {task.humanQA!.map((e, i) => (
                   <div key={i} style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
                     <div style={{
-                      padding: '5px 7px', background: 'var(--cth-lilac-light, #ece2f5)',
+                      display: 'flex', gap: 6, padding: '5px 7px',
+                      background: 'var(--cth-lilac-light, #ece2f5)',
                       boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)',
-                      fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-900)', whiteSpace: 'pre-wrap'
+                      fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-900)'
                     }}>
-                      <span style={{ fontFamily: 'var(--cth-font-display)', fontSize: 8, marginRight: 6 }}>Q</span>
-                      {e.q}
+                      <span style={{ fontFamily: 'var(--cth-font-display)', fontSize: 8, flexShrink: 0, marginTop: 2 }}>Q</span>
+                      <div style={{ flex: 1, minWidth: 0 }}>
+                        <MarkdownPreview source={e.q} variant="card" />
+                      </div>
                     </div>
                     {e.a ? (
                       <div style={{
-                        padding: '5px 7px', background: 'var(--cth-mint-light, #d9eed9)',
+                        display: 'flex', gap: 6, padding: '5px 7px',
+                        background: 'var(--cth-mint-light, #d9eed9)',
                         boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)',
-                        fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-900)', whiteSpace: 'pre-wrap'
+                        fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-900)'
                       }}>
-                        <span style={{ fontFamily: 'var(--cth-font-display)', fontSize: 8, marginRight: 6 }}>A</span>
-                        {e.a}
+                        <span style={{ fontFamily: 'var(--cth-font-display)', fontSize: 8, flexShrink: 0, marginTop: 2 }}>A</span>
+                        <div style={{ flex: 1, minWidth: 0 }}>
+                          <MarkdownPreview source={e.a} variant="card" />
+                        </div>
                       </div>
                     ) : (
                       <div style={{ fontSize: 11, color: 'var(--cth-coral)', fontFamily: 'var(--cth-font-display)' }}>

src/renderer/src/design/global.css

@@ -261,3 +261,37 @@ canvas, img, svg { image-rendering: pixelated; image-rendering: crisp-edges; }
   background: var(--cth-cream-200); box-shadow: inset 0 0 0 1px var(--cth-ink-100);
   color: var(--cth-ink-500); border-radius: 2px;
 }
+
+/* ─── Markdown inside a card (v0.4.6) ────────────────────────────────────────
+   The same renderer, hosted in a surface that already has its own type: the
+   ASK ME question and the task detail's Q&A trail. It inherits the host's face
+   and size (the mono face those cards set, not the UI face) and drops the document
+   chrome — no 72ch measure, no page padding — so a one-line question is still
+   one line. Every size below is relative, so the host sets the scale. */
+.cth-md-preview.cth-md-card {
+  font-family: inherit; font-size: inherit; line-height: inherit;
+  max-width: none; padding: 0;
+  /* A long path or URL in an agent's question wraps rather than widening the
+     card: the ASK ME column is narrow and does not scroll sideways. */
+  overflow-wrap: anywhere;
+}
+.cth-md-card > :first-child { margin-top: 0; }
+.cth-md-card > :last-child { margin-bottom: 0; }
+.cth-md-card p { margin: 1.1em 0; }
+.cth-md-card h1, .cth-md-card h2, .cth-md-card h3,
+.cth-md-card h4, .cth-md-card h5 {
+  margin: 0.8em 0 0.3em; border-bottom: none; padding-bottom: 0;
+}
+.cth-md-card h1 { font-size: 1.25em; }
+.cth-md-card h2 { font-size: 1.15em; }
+.cth-md-card h3, .cth-md-card h4, .cth-md-card h5 { font-size: 1.05em; }
+.cth-md-card code { font-size: 0.9em; padding: 0 3px; }
+.cth-md-card pre { margin: 0.5em 0; padding: 6px 8px; }
+/* 22px, not less: the list marker is painted OUTSIDE the padding box, and a
+   tighter indent clips "1." against the card's own 9px edge. */
+.cth-md-card ul, .cth-md-card ol { padding-left: 22px; margin: 0.4em 0; }
+.cth-md-card li { margin: 1px 0; }
+.cth-md-card blockquote { margin: 0.5em 0; padding-left: 10px; }
+.cth-md-card hr { margin: 0.8em 0; }
+.cth-md-card table { margin: 0.5em 0; }
+.cth-md-card th, .cth-md-card td { padding: 3px 7px; font-size: 0.9em; }