hilos-agent 0.11.12 → 0.11.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.12",
+  "version": "0.11.13",
   "description": "Run your own coding agent (Claude Code, Codex, Cursor, OpenCode, Hermes, or any command) as a teammate in a hilos room. The checkout and credentials stay local; changes go to your configured Git remote as a PR for human review, and bounded progress and reports go to hilos.",
   "type": "module",
   "bin": {

package/src/acp-session.mjs

@@ -19,6 +19,7 @@
 import { spawn } from "node:child_process";
 import { createAcpEventMapper } from "./agent-events.mjs";
 import { resolveHilosPermissionReply } from "./permission-gate.mjs";
+import { abortError, isObject, raceWithAbort } from "./util.mjs";
 
 const DEFAULT_TIMEOUT_MS = 30 * 60_000;
 const DEFAULT_POLL_MS = 1_000;
@@ -26,35 +27,6 @@ const SHUTDOWN_GRACE_MS = 750;
 const PROTOCOL_VERSION = 1;
 const MAX_LINE_BYTES = 4 * 1024 * 1024;
 
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function abortError(reason = "cancelled") {
-  const error = new Error(String(reason || "cancelled"));
-  error.name = "AbortError";
-  return error;
-}
-
-function raceWithAbort(promise, signal) {
-  if (!signal) return promise;
-  if (signal.aborted) return Promise.reject(abortError(signal.reason));
-  return new Promise((resolve, reject) => {
-    const onAbort = () => reject(abortError(signal.reason));
-    signal.addEventListener("abort", onAbort, { once: true });
-    Promise.resolve(promise).then(
-      (value) => {
-        signal.removeEventListener("abort", onAbort);
-        resolve(value);
-      },
-      (error) => {
-        signal.removeEventListener("abort", onAbort);
-        reject(error);
-      },
-    );
-  });
-}
-
 /**
  * Choose the agent's option id for a hilos reply ("once"|"always"|"reject").
  * Matches on the ACP option `kind` first (allow_once / allow_always /

package/src/agent-events.mjs

@@ -16,16 +16,16 @@
 //     stripped, length capped) — a chatty CLI can echo a `Bearer …` header.
 //
 // Claude shapes here MATCH `lib/hosted-worklog.ts` / `lib/hosted-agent.ts`
-// (`formatClaudeEvent`, `parseStreamResult`) so ticket 0274 can swap the daemon's
-// hand-rolled `lastLine` capture (see handler.mjs onData ~:787) for this parser
-// with zero behavior change. NOTHING imports this yet except the test — wiring is
-// 0274.
+// (`formatClaudeEvent`, `parseStreamResult`) so the daemon and the hosted path
+// render the same run from the same shapes (0274).
+
+import { COMMAND_LABEL_MAX, truncate } from "./util.mjs";
 
 /**
  * @typedef {object} AgentEvent
  * A normalized, render-ready step. Exactly one of these per meaningful thing the
  * coding agent did. Small on purpose — the LiveRunCard maps `t` to a label.
- * @property {'phase'|'edit'|'run'|'read'|'think'|'note'|'session'|'result'|'usage'|'websearch'|'webfetch'|'subagent'} t
+ * @property {'edit'|'run'|'read'|'think'|'note'|'session'|'result'|'usage'|'websearch'|'webfetch'|'subagent'} t
  *   - 'session' → { sessionId }        the CLI's resumable session id (init only)
  *   - 'edit'    → { path }             wrote/edited a file
  *   - 'read'    → { path }             read a file
@@ -44,9 +44,6 @@
  *                                      reported it (0787). Never a step — the
  *                                      ring and the activity fold skip it; it
  *                                      rides home on the report instead.
- *   - 'phase'   → { name }             reserved lifecycle marker (unused by v1
- *                                       parsers; kept so 0274 can add start/end
- *                                       phases without widening the type)
  * @property {string} [sessionId]
  * @property {string} [path]
  * @property {string} [cmd]
@@ -95,7 +92,7 @@ export function sanitizeText(value) {
   if (typeof value !== "string") return "";
   let out = value;
   for (const re of SECRET_PATTERNS) out = out.replace(re, REDACTED);
-  if (out.length > MAX_LEN) out = out.slice(0, MAX_LEN - 1) + "…";
+  out = truncate(out, MAX_LEN);
   return out;
 }
 
@@ -269,7 +266,7 @@ function webPhrase(value) {
   // would render.
   const clean = sanitizeText(raw);
   if (!clean) return "";
-  return clean.length > WEB_LABEL_MAX ? clean.slice(0, WEB_LABEL_MAX - 1) + "…" : clean;
+  return truncate(clean, WEB_LABEL_MAX);
 }
 
 /**
@@ -879,7 +876,7 @@ function normalizeVendor(vendor) {
 // --- Streaming parsers -----------------------------------------------------
 
 /**
- * The daemon pushes raw stdout chunks (see handler.mjs onData ~:787) that can
+ * The daemon pushes raw stdout chunks (handler.mjs `handleCliData`) that can
  * split a JSON object mid-line. A structured parser buffers the partial tail and
  * only parses COMPLETE lines; flush() drains a trailing unterminated line.
  * @param {(line: string) => AgentEvent[]} parseLine
@@ -913,7 +910,7 @@ function makeLineBufferedParser(parseLine) {
  * Fallback for any vendor with no structured stream (cursor graduated to a
  * real parser in 0573). There's nothing to parse, so we only remember the last
  * non-empty line seen — matching exactly what the daemon does today
- * (handler.mjs onData) so we NEVER regress below it — and emit at most one
+ * (handler.mjs `handleCliData`) so we NEVER regress below it — and emit at most one
  * sparse note on flush.
  */
 function makeTextTailParser() {
@@ -964,13 +961,13 @@ function describeRun(cmd) {
   const c = String(cmd || "").trim();
   if (!c) return "Running a command";
   if (/\b(test|tests)\b|vitest|jest|pytest|\bgo test\b/i.test(c)) return "Running tests";
-  const short = c.length > 60 ? c.slice(0, 59) + "…" : c;
+  const short = truncate(c, COMMAND_LABEL_MAX);
   return `Running ${short}`;
 }
 
 /**
  * One AgentEvent → a human step label, or null for events that aren't shown as
- * steps (session/phase are metadata). Pure.
+ * steps (session events are metadata). Pure.
  * @param {AgentEvent} event
  * @returns {string | null}
  */
@@ -993,7 +990,7 @@ export function stepLabel(event) {
     case "result":
       return event.ok ? "Done" : "Finished with errors";
     default:
-      return null; // session / phase / unknown → not a step
+      return null; // session / unknown → not a step
   }
 }
 
@@ -1081,7 +1078,7 @@ function activitySentence(row) {
  * truth a CLI stream carries, so "done" is the sequential-execution inference:
  * a new action starting settles the one in flight. `settle("failed")` is for a
  * dying run — leaving "Editing…" forever is the dishonesty this feed exists to
- * avoid. session/phase events are metadata, not rows (same as stepLabel).
+ * avoid. session events are metadata, not rows (same as stepLabel).
  * @param {number} [limit]
  */
 export function createActivityFold(limit = MAX_ACTIVITY) {
@@ -1151,7 +1148,7 @@ export function createActivityFold(limit = MAX_ACTIVITY) {
         });
         return;
       default:
-        return; // session / phase / unknown — metadata, not activity
+        return; // session / unknown — metadata, not activity
     }
   }
 

package/src/agent-result.mjs

@@ -0,0 +1,54 @@
+// 1298 — one writing contract and final-result envelope for hosted and local runs.
+export const AGENT_REPLY_STYLE_RULE = [
+  "How to write the reply:",
+  "- Lead with the answer or outcome. Never restate the request.",
+  "- Default to 1-3 short sentences, or at most three short bullets for separate outcomes.",
+  "- Include useful links once. No preamble, headings, sign-off, process narration, or routine test/file lists.",
+  "- Keep blockers, material limitations, and a needed next step visible. Never claim checks, deployment, or merging without evidence.",
+  "- Give requested documents, plans, code, research, and explanations the detail they need; keep their introduction short. Put code and commands in fenced blocks.",
+  "The room's voice may shape tone, but only a person's request for detail expands this default. Clarity beats a word limit.",
+].join("\n");
+
+export const AGENT_CODE_RESULT_RULE = [
+  AGENT_REPLY_STYLE_RULE,
+  "When the coding turn finishes, return one fenced hilos-result JSON object with three string fields:",
+  '{"summary":"The short result for the teammate.","prTitle":"A short title describing the actual problem fixed","prDescription":"The problem, resulting behavior, and relevant verification."}',
+  "Write summary for someone who may never open the code. Do not repeat the PR title, request, branch, file counts, or tool history. Include material limitations.",
+  "Write prTitle and prDescription as the pull request itself for a reviewer opening it cold. Title: under 60 characters, no trailing period or request echo. Description: usually 1-2 short paragraphs; only actual checks. No transcript, preamble, boilerplate, or attribution footer; hilos adds credit.",
+  "If you create or update the PR yourself, use those same title and description fields on GitHub. Describe the entire final PR change, including prior work on an iteration. Preserve text a person edited.",
+  "Return empty PR fields when there is no code change. A VISUAL_PREVIEW: /route line may follow the fence.",
+].join("\n");
+
+/** Keep complete artifacts, never half a sentence, Markdown link, or JSON object. */
+export function retainAgentResult(value) {
+  return typeof value === "string" && value.length <= 32_000 ? value.trim() : "";
+}
+
+/** @returns {{ summary: string, prTitle: string, prDescription: string } | null} */
+export function readAgentResult(value) {
+  const text = retainAgentResult(value);
+  const fenced = /```hilos-result\s*\n([\s\S]*?)\n```/.exec(text);
+  const candidate = fenced?.[1] ?? (text.startsWith("{") ? text : null);
+  if (!candidate) return null;
+  try {
+    const result = JSON.parse(candidate);
+    if (!result || typeof result !== "object" || typeof result.summary !== "string" ||
+        typeof result.prTitle !== "string" || typeof result.prDescription !== "string") return null;
+    return {
+      summary: result.summary.trim(),
+      prTitle: result.prTitle.trim(),
+      prDescription: result.prDescription.trim(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Legacy prose remains readable; an invalid machine envelope never enters chat. */
+export function agentResultText(value) {
+  const text = retainAgentResult(value);
+  const result = readAgentResult(text);
+  if (result) return result.summary;
+  if (text.includes("```hilos-result") || /^\s*\{\s*"(?:summary|prTitle|prDescription)"/.test(text)) return "";
+  return text.replace(/^\s*VISUAL_PREVIEW:.*$/gm, "").trim();
+}

package/src/child-mcp.mjs

@@ -147,7 +147,7 @@ export function childMcpPlanned({ cfg, vendor, bindingClaim, env } = {}) {
 }
 
 /** The `mcpServers` fragment for a claude `--mcp-config` JSON. */
-export function childMcpServers(url) {
+function childMcpServers(url) {
   return { [CHILD_MCP_SERVER]: { type: "http", url } };
 }
 
@@ -159,7 +159,7 @@ export function childMcpServers(url) {
  * config file instead — claude takes `--mcp-config` more than once, but one
  * file the run owns end-to-end is one file to delete.
  */
-export function writeChildMcpConfig(url, { dir = os.tmpdir() } = {}) {
+function writeChildMcpConfig(url, { dir = os.tmpdir() } = {}) {
   const configPath = path.join(
     dir,
     `hilos-child-mcp-${process.pid}-${randomBytes(6).toString("hex")}.json`,

package/src/claude-permissions.mjs

@@ -38,6 +38,7 @@ import {
   DEFAULT_PERMISSION_TIMEOUT_MS,
   resolveHilosPermissionReply,
 } from "./permission-gate.mjs";
+import { isObject } from "./util.mjs";
 
 /** The MCP server key and tool name the daemon serves. Together they form the
  *  `mcp__<server>__<tool>` identifier claude's flag takes. */
@@ -54,10 +55,6 @@ const DEFAULT_SESSION_ID_WAIT_MS = 10_000;
 /** Tool names whose input names a file rather than a command. */
 const FILE_INPUT_KEYS = ["file_path", "path", "notebook_path"];
 
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Shape claude's permission-prompt payload into the SAME vendor-neutral request
  * the opencode/ACP card flow already produces, so the card, its audit row, and
@@ -184,9 +181,6 @@ export function claudePermissionArgs({
   ];
 }
 
-/** The flags to strip when a CLI turns out not to know them (compat retry). */
-export const CLAUDE_PERMISSION_FLAGS = ["--mcp-config", "--permission-prompt-tool"];
-
 /**
  * Serve the permission tool on loopback for the life of one run.
  *
@@ -209,8 +203,7 @@ export const CLAUDE_PERMISSION_FLAGS = ["--mcp-config", "--permission-prompt-too
  *   allowedTools?: string,
  * }} options
  * @returns {Promise<{ configPath: string, toolId: string, url: string, port: number,
- *   args: string[], setSessionId: (value: string) => void, pending: () => number,
- *   close: () => Promise<void> }>}
+ *   args: string[], close: () => Promise<void> }>}
  */
 export async function startClaudePermissionServer({
   requestPermission,
@@ -235,7 +228,6 @@ export async function startClaudePermissionServer({
   }
   const token = randomBytes(24).toString("hex");
   let seq = 0;
-  let inflight = 0;
   let currentSessionId = String(sessionId || "");
   // hilos's server REJECTS a permission request with an empty vendorSessionId,
   // so a fresh run (no session to resume) must not ask with one — every card
@@ -373,33 +365,25 @@ export async function startClaudePermissionServer({
         sessionId: await sessionIdForAsk(),
         fallbackId: String(++seq),
       });
-      inflight++;
-      let outcome = "transport-error";
-      // Set only when a workspace RULE refused this ask (0813); a person's
-      // rejection leaves these alone and keeps the human wording. Provenance is
-      // tracked apart from the reason because a rule may carry no reason.
-      let byPolicy = false;
-      let policyReason = null;
-      let decisionReply = "reject";
-      try {
-        const resolved = await resolveHilosPermissionReply({
-          request,
-          requestPermission,
-          getPermissionDecision,
-          signal,
-          timeoutMs,
-          pollIntervalMs,
-          log,
-          label: "claude permission",
-          localAllow,
-        });
-        decisionReply = resolved.reply;
-        outcome = resolved.outcome;
-        byPolicy = resolved.byPolicy === true;
-        policyReason = resolved.policyReason ?? null;
-      } finally {
-        inflight--;
-      }
+      const resolved = await resolveHilosPermissionReply({
+        request,
+        requestPermission,
+        getPermissionDecision,
+        signal,
+        timeoutMs,
+        pollIntervalMs,
+        log,
+        label: "claude permission",
+        localAllow,
+      });
+      const decisionReply = resolved.reply;
+      const outcome = resolved.outcome;
+      // byPolicy is set only when a workspace RULE refused this ask (0813); a
+      // person's rejection leaves it false and keeps the human wording.
+      // Provenance is tracked apart from the reason because a rule may carry no
+      // reason.
+      const byPolicy = resolved.byPolicy === true;
+      const policyReason = resolved.policyReason ?? null;
       // A rejection is never an MCP error: an isError result makes claude retry
       // or improvise around the block. A plain deny result is the refusal the
       // CLI is built to respect.
@@ -452,11 +436,6 @@ export async function startClaudePermissionServer({
     url,
     port,
     args: claudePermissionArgs({ configPath, allowedTools }),
-    /** Let the caller stamp the CLI's real session id onto later cards. */
-    setSessionId(value) {
-      if (typeof value === "string" && value) currentSessionId = value;
-    },
-    pending: () => inflight,
     async close() {
       try {
         fs.unlinkSync(configPath);

package/src/cli.mjs

@@ -6,6 +6,7 @@
 // logs a periodic "still working…" heartbeat so the run visibly stays alive.
 
 import { spawn } from "node:child_process";
+import { truncate } from "./util.mjs";
 
 /**
  * Let the daemon finish its existing abort/cleanup path before exiting.
@@ -150,8 +151,7 @@ export function fmtElapsed(ms) {
 
 /** Collapse to one trimmed, length-capped line (for a heartbeat's "Latest:" tail). */
 export function oneLine(s, max = 140) {
-  const t = String(s || "").replace(/\s+/g, " ").trim();
-  return t.length > max ? t.slice(0, max - 1) + "…" : t;
+  return truncate(String(s || "").replace(/\s+/g, " ").trim(), max);
 }
 
 /**

package/src/codex-mcp-session.mjs

@@ -58,6 +58,7 @@ import {
   DEFAULT_PERMISSION_TIMEOUT_MS,
   resolveHilosPermissionReply,
 } from "./permission-gate.mjs";
+import { isObject } from "./util.mjs";
 
 // Codex 0.153.4 accepts on-request/never on its MCP tool. `untrusted`
 // is rejected before a turn starts. Keep the workspace sandbox and route its
@@ -65,16 +66,6 @@ import {
 const DEFAULT_TIMEOUT_MS = 30 * 60_000;
 const SHUTDOWN_GRACE_MS = 750;
 
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function abortError(reason = "cancelled") {
-  const error = new Error(String(reason || "cancelled"));
-  error.name = "AbortError";
-  return error;
-}
-
 /**
  * Render codex's argv-array command as the one line a human decides about.
  * Codex wraps shell work as ["/bin/zsh","-lc","<the real command>"]; showing

package/src/config.mjs

@@ -40,7 +40,7 @@ function readJson(path) {
 }
 
 /** First config file that exists: explicit path → ./hilos-agent.json → ~/.hilos/agent.json. */
-export function findConfigPath(explicit) {
+function findConfigPath(explicit) {
   if (explicit) return explicit;
   if (existsSync(LOCAL_CONFIG)) return LOCAL_CONFIG;
   if (existsSync(GLOBAL_CONFIG)) return GLOBAL_CONFIG;
@@ -180,10 +180,9 @@ const DEFAULTS = {
   // Cap a chat reply / plan-ack so a stalled model can't dead-air the channel;
   // on timeout we post an honest "taking longer than expected" line.
   chatTimeoutMs: 90000,
-  // Work queue: run mentions one at a time (concurrency 1 — parallel CLI runs on
-  // one checkout would collide on git state). queueAcks posts "queued behind the
-  // current task" when a mention lands during a run; set false to keep it quiet.
-  queueConcurrency: 1,
+  // Work queue: mentions run one at a time — parallel CLI runs on one checkout
+  // would collide on git state. queueAcks posts "queued behind the current task"
+  // when a mention lands during a run; set false to keep it quiet.
   queueAcks: true,
   runTimeoutMs: 600000,
   decisionTimeoutMs: 1800000,
@@ -303,8 +302,7 @@ const LIVE_FIELDS = [
   "heartbeatMs",
   "progressMs",
   "chatTimeoutMs",
-  // NOT queueConcurrency: the queue is built once at startup, so it can't change
-  // live. queueAcks IS live (intake() reads it per-mention from liveCfg).
+  // Live: intake() reads it per-mention from liveCfg.
   "queueAcks",
   // folders is an object map; it's listed here for documentation, but the actual
   // live merge (with DEFAULTS) happens in the special-cased block below, exactly

package/src/daemon.mjs

@@ -1,5 +1,5 @@
-// Pure daemon helpers — no I/O. (Mirror of the app's scripts/lib/daemon.mjs so
-// the package stands alone; keep them equivalent.)
+// Pure daemon helpers — no I/O.
+import { agentResultText } from "./agent-result.mjs";
 
 import {
   agentCoauthorTrailer,
@@ -133,7 +133,7 @@ export function commitMessage(task, provenance = {}) {
   const title = selectGithubArtifactTitle({
     summary: provenance.summary,
     originalTask: task,
-    fallback: "hilos change",
+    fallback: "Update project files",
   });
   const trailer = agentCoauthorTrailer(provenance.agentName, provenance.agentId);
   // The agent's own account of the change becomes the commit body, so the log
@@ -152,28 +152,23 @@ export function prTitleBody(task, branch, provenance = {}) {
   const title = selectGithubArtifactTitle({
     summary: provenance.summary,
     originalTask: task,
-    fallback: branch,
+    fallback: "Update project files",
   });
-  return { title, body: githubArtifactBody(provenance) };
+  return { title, body: githubArtifactBody({ ...provenance, title }) };
 }
 
 /** Build the post_report payload that serves as the approval card. */
 export function buildProposalReport(o) {
-  const firstLine = String(o.task || "").split("\n")[0].slice(0, 72) || "task";
-  const statLine = `${o.stat.files} file(s), +${o.stat.insertions}/-${o.stat.deletions} on \`${o.branch}\` in ${o.repoFullName}`;
   const diffBlock =
     "```diff\n" +
     o.diffText +
     (o.truncated ? `\n… (+${o.omittedLines} more lines)` : "") +
     "\n```";
-  // Tag whoever asked so the proposal lands in their notifications, not just
-  // the channel. Handle matches the server's @-mention format (kebab of name).
-  const handle = mentionHandle(o.requester);
-  const lead = handle ? `@${handle} — proposed changes for: ${firstLine}` : `Proposed changes for: ${firstLine}`;
-  const summary = `${lead}\n\n${statLine}\n\n${diffBlock}`;
+  // Before a PR exists, the diff is the reviewable deliverable.
+  const summary = `${agentResultText(o.summary) || "Changes are ready for review."}\n\n${diffBlock}`;
   const caveats = ["Not pushed yet — approve to push + open a PR, or reject to discard."];
   if (o.runFailed) caveats.push("The coding agent exited non-zero; review the diff carefully.");
-  return { title: `Proposal: ${firstLine}`, summary, caveats, todos: [] };
+  return { title: "Ready for review", summary, caveats, todos: [] };
 }
 
 /** kebab handle from a display name (matches the server's mention handle). */

package/src/deploy.mjs

@@ -16,7 +16,7 @@ function isProvider(value) {
   return DEPLOY_PROVIDERS.includes(value);
 }
 
-export function findDeployCli(provider, env = process.env) {
+function findDeployCli(provider, env = process.env) {
   if (!isProvider(provider)) return null;
   for (const entry of String(env.PATH || "").split(delimiter)) {
     if (!entry) continue;

package/src/github-artifacts.mjs

@@ -1,14 +1,17 @@
+import { readAgentResult, agentResultText } from "./agent-result.mjs";
 const TITLE_MAX = 72;
 // A pull-request description is a reviewer's first read, not an essay: enough
 // room for the agent's own account of the change, bounded so a runaway summary
 // can never become the PR body. The commit log gets a shorter form still.
-const DESCRIPTION_MAX = 1400;
+const DESCRIPTION_MAX = 6000;
 const COMMIT_BODY_MAX = 600;
 
 const REJECTED_TITLE_LINES = [
   /^(?:sure|okay|ok|yes|got it|sounds good|absolutely|certainly|done|working on it)\b/i,
   /^(?:i(?:'ll| will| have|’ll)|let me|here(?:'s| is))\b/i,
   /^(?:address|apply|handle|incorporate|respond to|update)\b.{0,36}\b(?:feedback|review|comments?|pr)\b/i,
+  /^(?:summary|changes|what changed|verification|testing|result|done|update|implementation)[:\s]*$/i,
+  /^(?:can|could|would|please|hey|hi)\b/i,
   /^@\S+/,
   /https?:\/\//i,
   /^```/,
@@ -57,13 +60,16 @@ function truncateTitle(title) {
 /**
  * The title the agent wrote for its OWN change, or null when its summary never
  * offered a usable one. Callers that must always end up with something use
- * `selectGithubArtifactTitle` (which falls back to the request text); callers
+ * `selectGithubArtifactTitle` (which uses a neutral fallback); callers
  * that need to know whether the agent actually authored a headline — an
  * iteration commit deciding between the agent's words and a canned subject —
  * use this.
  */
 /** @param {unknown} summary */
 export function agentAuthoredTitle(summary) {
+  const result = readAgentResult(summary);
+  if (result) return usableTitle(cleanTitleLine(result.prTitle)) ? truncateTitle(cleanTitleLine(result.prTitle)) : null;
+  if (!agentResultText(summary)) return null;
   const line = candidateLines(summary).find(usableTitle);
   return line ? truncateTitle(line) : null;
 }
@@ -75,12 +81,11 @@ export function agentAuthoredTitle(summary) {
  * callers keep their existing PR title and use this only for the new commit.
  */
 /** @param {{ summary?: unknown, originalTask?: unknown, fallback?: string }} [input] */
-export function selectGithubArtifactTitle({ summary, originalTask, fallback = "Update" } = {}) {
+export function selectGithubArtifactTitle({ summary, originalTask, fallback = "Update project files" } = {}) {
   const summaryTitle = agentAuthoredTitle(summary);
-  const taskTitle = candidateLines(originalTask)
-    .map((line) => line.replace(/@[a-z0-9][a-z0-9-]*/gi, "").trim())
-    .find(usableTitle);
-  return truncateTitle(summaryTitle || taskTitle || cleanTitleLine(fallback) || "Update");
+  const taskText = candidateLines(originalTask).join(" ").toLowerCase();
+  const echoed = summaryTitle && cleanTitleLine(summaryTitle).toLowerCase() === taskText;
+  return truncateTitle((!echoed && summaryTitle) || cleanTitleLine(fallback) || "Update project files");
 }
 
 /**
@@ -142,11 +147,14 @@ function clampLines(lines, max) {
  */
 /** @param {unknown} summary @param {{ max?: number }} [options] */
 export function agentChangeDescription(summary, { max = DESCRIPTION_MAX } = {}) {
-  const lines = String(summary ?? "")
-    .replace(/\r\n?/g, "\n")
-    .split("\n");
+  const result = readAgentResult(summary);
+  if (result) return clampLines(tidyLines((result.prDescription || result.summary).split("\n").map(defuseMarkup)), max);
+  const text = agentResultText(summary);
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
   const headline = lines.findIndex((line) => usableTitle(cleanTitleLine(line)));
-  const body = (headline === -1 ? lines : lines.slice(headline + 1))
+  // A single sentence is the complete description, not a headline to discard.
+  const hasBody = headline >= 0 && lines.slice(headline + 1).some((line) => line.trim() && !/^\s*VISUAL_PREVIEW:/i.test(line));
+  const body = (hasBody ? lines.slice(headline + 1) : lines)
     .filter((line) => !/^\s*visual_?preview\s*:/i.test(line))
     .map(defuseMarkup);
   return clampLines(tidyLines(body), max);
@@ -155,6 +163,8 @@ export function agentChangeDescription(summary, { max = DESCRIPTION_MAX } = {})
 /** The same account of the change, shortened and de-fenced for a commit body. */
 /** @param {unknown} summary */
 export function agentCommitBody(summary) {
+  const result = readAgentResult(summary);
+  if (result) return clampLines(tidyLines(stripFences(result.prDescription || result.summary).split("\n").map(defuseMarkup)), COMMIT_BODY_MAX);
   return agentChangeDescription(stripFences(summary), { max: COMMIT_BODY_MAX });
 }
 
@@ -185,10 +195,6 @@ function safeHilosUrl(value) {
   }
 }
 
-function linkLine(label, url, fallback) {
-  return url ? `- ${label}: [Open in hilos](${url})` : `- ${label}: ${fallback}`;
-}
-
 /**
  * A bounded PR body: the agent's own description of the change on top, then the
  * provenance block. It still deliberately never accepts task text — the raw
@@ -199,7 +205,7 @@ function linkLine(label, url, fallback) {
 /**
  * @param {{ agentName?: unknown, personName?: unknown, roomName?: unknown,
  * roomUrl?: unknown, messageId?: unknown, messageUrl?: unknown, runId?: unknown,
- * reportId?: unknown, partial?: boolean, summary?: unknown }} [input]
+ * reportId?: unknown, partial?: boolean, summary?: unknown, title?: string }} [input]
  */
 export function githubArtifactBody(input = {}) {
   const agent = safeLabel(input.agentName, "hilos agent");
@@ -223,25 +229,14 @@ export function githubArtifactBody(input = {}) {
     ? "\nThis is a partial run. Mention the agent in the room to continue."
     : "";
 
-  // The agent's account of the change leads, because that is what a reviewer
-  // opens the pull request to read. Provenance follows it under a rule.
-  const description = agentChangeDescription(input.summary);
-
-  return [
-    ...(description ? [description, "", "---", ""] : []),
-    `Proposed by **${agent}** for **${person}** in **${room}**. A person remains the creator of record and decides whether to merge.`,
-    "",
-    linkLine("Room", roomUrl, room),
-    linkLine("Request", messageUrl, machine.messageId ? `message \`${machine.messageId}\`` : "room request"),
-    `- Run: ${runId ? `\`${runId}\`` : "not recorded"}`,
-    `- Report: ${reportId ? `\`${reportId}\`` : "posted in the room after this pull request opens"}`,
-    partialNote,
-    "",
-    `<!-- hilos-provenance ${JSON.stringify(machine).replace(/--/g, "—")} -->`,
-  ]
-    .filter((line, index, all) => line !== "" || index === 1 || all[index - 1] !== "")
-    .join("\n")
-    .trim();
+  const description = agentChangeDescription(input.summary) || "Changes are available in the diff. Verification was not reported.";
+  const context = messageUrl || roomUrl;
+  const credit = `Requested by **${person}** · Agent: **${agent}**${context ? ` · [Context](${context})` : ""}`;
+  const visible = [description, partialNote.trim(), credit].filter(Boolean).join("\n\n");
+  const title = input.title || selectGithubArtifactTitle({ summary: input.summary });
+  const marker = { ...machine, generatedTitle: `${partial ? "[partial] " : ""}${title}`, generatedBody: visible };
+  return `${visible}\n\n<!-- hilos-provenance ${JSON.stringify(marker).replace(/--/g, "\\u002d\\u002d")} -->`;
+
 }
 
 /** A stable Git co-author trailer for the named agent, without user input. */
@@ -251,3 +246,22 @@ export function agentCoauthorTrailer(agentName, agentId) {
   const id = safeId(agentId)?.replace(/[^a-zA-Z0-9]/g, "").slice(0, 48) || "agent";
   return `Co-authored-by: ${name} <agent+${id}@hilos.sh>`;
 }
+
+/** Update only text still identical to what hilos last wrote (1298).
+ * @returns {{title?: string, body?: string}}
+ */
+export function githubArtifactPatch(existing, input) {
+  const match = /<!-- hilos-provenance (\{[^\n]*\}) -->/.exec(existing.body || "");
+  if (!match) return {};
+  let previous;
+  try { previous = JSON.parse(match[1]); } catch { return {}; }
+  const patch = {};
+  const title = input.title || selectGithubArtifactTitle({ summary: input.summary });
+  if (typeof previous.generatedTitle === "string" && existing.title === previous.generatedTitle) {
+    patch.title = `${input.partial ? "[partial] " : ""}${title}`;
+  }
+  if (typeof previous.generatedBody === "string" && (existing.body || "").slice(0, match.index).trim() === previous.generatedBody) {
+    patch.body = githubArtifactBody(input) + (existing.body || "").slice(match.index + match[0].length);
+  }
+  return patch;
+}