hilos-agent 0.1.16 → 0.4.0

package/src/handler.mjs

@@ -9,13 +9,15 @@
 
 import { spawnSync } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { rmSync, mkdtempSync } from "node:fs";
+import { rmSync, mkdtempSync, existsSync } from "node:fs";
 import { hostname, tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   branchSlug,
   truncateDiff,
   resolveRepoPath,
+  resolveFolderPath,
+  diffStatusSets,
   parseShortstat,
   buildProposalReport,
   decisionKind,
@@ -24,7 +26,7 @@ import {
   mentionHandle,
   detectPrContinuation,
 } from "./daemon.mjs";
-import { runCli, buildHeartbeat, ackText, oneLine } from "./cli.mjs";
+import { runCli, buildHeartbeat, ackText, oneLine, fmtElapsed } from "./cli.mjs";
 import { makeStreamParser } from "./agent-events.mjs";
 import { detectVendor, codeStreamArgs, createProgressEmitter } from "./progress-emitter.mjs";
 import { resolveFollowupMode, classifyFollowupCue, normalizeSignal } from "./followup.mjs";
@@ -80,10 +82,26 @@ function requesterTag(author) {
   return handle ? `@${handle}` : "";
 }
 
+function compactRunMarker(status, branch) {
+  const b = branch ? ` \`${branch}\`` : "";
+  if (status === "pushed") return `Needs review:${b}`;
+  if (status === "discarded" || status === "cancelled") return `Stopped:${b}`;
+  if (status === "no-changes") return `Done:${b}`;
+  if (status === "changes" || status === "timeout") return `Needs follow-up:${b}`;
+  return `Failed:${b}`;
+}
+
 function defaultDeps() {
   return {
     git: (cwd, args) =>
       spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: 50 * 1024 * 1024 }),
+    // The async CLI runner, injectable so folder mode (and tests) can drive the
+    // coding run without spawning a real process. The repo flow still uses the
+    // imported runCli directly (unchanged); only folder mode goes through deps.
+    runCli: (opts) => runCli(opts),
+    // Does a path exist on disk? Injectable so folder mode's "missing folder"
+    // guard is unit-testable without touching the real filesystem.
+    pathExists: (p) => existsSync(p),
     openPR: (cwd, { title, body, branch, base }) => {
       const r = spawnSync(
         "gh",
@@ -166,9 +184,9 @@ async function linkPrFromUrl({ tool, channelId, url }) {
 async function applyDecision({ decision, repoPath, branch, task, requester, cfg, tool, channelId, deps, parentId, existingPrUrl, settleId, runId }) {
   const tag = requesterTag(requester);
   const lead = tag ? `${tag} — ` : "";
-  // `parentId` here is the run's thread root: every outcome below is terminal, so
-  // it broadcasts back to the channel (visible in both thread and channel) — the
-  // hosted runner's reply_broadcast. A no-op when there's no thread root.
+  // `parentId` here is the run's thread root. Terminal outcomes ask the server
+  // for channel visibility, but the workspace decides whether final agent
+  // results actually broadcast. A no-op when there's no thread root.
   if (decision.kind === "approved") {
     // Guard: nothing staged → don't push an empty branch and falsely report "shipped".
     if (deps.git(repoPath, ["diff", "--cached", "--quiet"]).status === 0) {
@@ -208,10 +226,9 @@ async function applyDecision({ decision, repoPath, branch, task, requester, cfg,
       ? { ok: true, url: existingPrUrl }
       : deps.openPR(repoPath, { title, body, branch, base: cfg.defaultBranch });
     // Seamless single card (0289): when a live status message was streaming this
-    // run, SETTLE the report onto it in place (broadcast keeps it channel-visible)
-    // so the one card cross-fades from live run → report — no separate progress
-    // message + separate report card. Without a status id (older server / status
-    // post failed) fall back to posting a fresh broadcast report as before.
+    // run, SETTLE the report onto it in place; the workspace setting decides
+    // whether that final report is also channel-visible. Without a status id
+    // (older server / status post failed) fall back to posting a fresh report.
     const reportArgs = {
       channelId,
       title: `Shipped: ${title}`,
@@ -296,8 +313,8 @@ async function shipSelfDriven({ repoPath, branch, task, requester, cfg, tool, ch
   }
   const { title } = prTitleBody(task, cur);
   // Seamless single card (0289): settle onto the live status message when one was
-  // streaming this run (broadcast keeps it channel-visible); otherwise a fresh
-  // broadcast report, exactly as before.
+  // streaming this run; the workspace setting decides channel visibility.
+  // Otherwise post a fresh final report.
   const reportArgs = {
     channelId,
     title: `Shipped: ${title}`,
@@ -352,7 +369,8 @@ const CODE_SIGNAL = "__CODE__";
  * `error` is set when the model produced nothing (so the caller can be honest
  * about a timeout vs a missing binary instead of inventing a reply).
  */
-async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cfg, signal, hasActiveRun = false }) {
+async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cfg, signal, hasActiveRun = false, runCliFn }) {
+  const doRun = runCliFn || runCli; // folder mode injects deps.runCli; repo flow uses the import
   const cmd = cfg.chatCmd || cfg.codingCmd;
   const parts = cmd.split(" ").filter(Boolean);
   // When this thread already owns an OPEN pull request (a follow-up reply), the
@@ -381,12 +399,13 @@ async function routeIntent({ name, repoFullName, transcript, workspaceMemory, cf
     `that lists who reacted with each emoji.\n\n` +
     `Otherwise — a question, a greeting, general discussion, or they explicitly don't want code ` +
     `yet — just reply to them concisely and directly as a single chat message (no preamble, no ` +
-    `headings). When unsure, prefer to act (${CODE_SIGNAL}); this is a build channel.` +
+    `headings). When unsure, stay conversational; implementation and PR flow are for clear ` +
+    `action language.` +
     `${followupBlock}\n\n` +
     `You are only routing here — output ONLY your text response. Do NOT use any tools, do NOT ` +
     `edit files, do NOT run commands; a separate step does the actual coding.\n\n` +
     `${memoryPreamble(workspaceMemory)}Conversation so far:\n${transcript}`;
-  const run = await runCli({
+  const run = await doRun({
     cmd: parts[0],
     args: [...parts.slice(1), prompt],
     timeoutMs: cfg.chatTimeoutMs || cfg.runTimeoutMs,
@@ -450,6 +469,34 @@ export function codeTaskPrompt(o) {
   return p;
 }
 
+/**
+ * The prompt handed to the coding CLI in FOLDER mode (0322): the agent works
+ * directly in the user's own folder — no branch, no PR, no commit step. Same
+ * imperative "edit files now" framing as codeTaskPrompt, but it tells the agent
+ * its edits land straight in the folder and bans git/gh (there's nothing for the
+ * daemon to commit; the changes ARE the deliverable).
+ * @param {{ message?: { body?: string } | null, context?: { transcript?: string } | null, brief?: string, folderPath?: string }} [o]
+ */
+export function folderTaskPrompt(o) {
+  const { message, context, brief, folderPath } = o || {};
+  const task = (brief && brief.trim()) || String(message?.body || "").trim();
+  const where = folderPath ? ` in the local folder ${folderPath}` : "";
+  let p =
+    `You are a coding agent working directly${where}. Implement the following by EDITING ` +
+    `FILES now — make the changes directly in this folder, do not just describe them, do not ` +
+    `ask questions:\n\n${task}`;
+  p +=
+    `\n\nIMPORTANT: your edits apply DIRECTLY to the user's folder — there is no branch, no ` +
+    `commit, and no pull request. Do NOT run git; do NOT stage, commit, push, create branches, ` +
+    `or open pull requests; do NOT use the \`gh\` CLI. Just leave your edits in the folder for ` +
+    `the person to review.`;
+  const transcript = context?.transcript?.trim();
+  if (transcript) {
+    p += `\n\nBackground from the team's discussion (context only — the task above is what to do):\n${transcript}`;
+  }
+  return p;
+}
+
 /** owner/name from a GitHub remote URL (https or ssh), or null. */
 export function normalizeRemote(url) {
   const m = String(url || "")
@@ -534,9 +581,15 @@ async function respondConversationally({ message, channelId, tool, me, cfg, repo
   const { transcript } = context || (await fetchContext({ channelId, tool, parentId }));
   const name = me?.agentName || "an assistant";
   // Tell the agent what the room is connected to so it doesn't ask "which repo?".
+  // repoLink is already folder-excluded (handleTask picks kind!=='folder'), so the
+  // "repository" line never claims a folder path is a repo. When there's no repo
+  // but this channel maps to a local folder on THIS machine, say that instead.
+  const folderPath = !repoLink ? resolveFolderPath(cfg, channelId) : null;
   const repoLine = repoLink
     ? `This channel is connected to the repository ${repoLink.repo_full_name}; assume that repo for any code work — don't ask which one.`
-    : `If asked to change code, note that a repo isn't linked to this channel yet.`;
+    : folderPath
+      ? `This channel is connected to the local folder ${folderPath} on this machine; assume that folder for any file work — don't ask which one.`
+      : `If asked to change code, note that a repo isn't linked to this channel yet.`;
   const prompt =
     `You are ${name}, a teammate in a team chat (hilos). Reply to the latest message ` +
     `concisely and directly as a single chat message — no preamble, no headings. ` +
@@ -629,6 +682,11 @@ export function isReviewRequest(message) {
   );
 }
 
+function agentMode(message) {
+  const mode = message?.agentMode || message?.metadata?.agentMode;
+  return mode === "ask" || mode === "ship" ? mode : null;
+}
+
 /** The PR url a review-request/review points at, from the mention's reviewOf or the
  *  channel's linked PR — whichever is present. */
 function reviewTargetPrUrl(message) {
@@ -707,6 +765,10 @@ async function reviewTask({ message, channelId, tool, me, cfg, workspaceMemory,
     body: `Reviewing ${label} now — I'll post my read shortly.`,
   }).catch(() => null);
   const threadRoot = parentId ?? ack?.messageId ?? null;
+  const updateReviewMarker = async (body) => {
+    if (!ack?.messageId || parentId) return;
+    await tool("edit_message", { messageId: ack.messageId, body }).catch(() => {});
+  };
 
   // The diff — the whole review is fed off this (no clone, no gh creds).
   // Capture the failure reason on BOTH error shapes: a soft failure returns
@@ -722,6 +784,7 @@ async function reviewTask({ message, channelId, tool, me, cfg, workspaceMemory,
       broadcast: Boolean(threadRoot),
       body: `I couldn't read ${label}'s diff to review it${why}. It may be private, merged, or not linked here.`,
     }).catch(() => {});
+    await updateReviewMarker(`Review failed: ${label}`);
     return { status: "review-no-diff" };
   }
 
@@ -771,6 +834,7 @@ async function reviewTask({ message, channelId, tool, me, cfg, workspaceMemory,
 
   if (run.aborted || signal?.aborted) {
     await tool("post_message", { channelId, parentId: threadRoot, body: `Stopped the review of ${label}.` }).catch(() => {});
+    await updateReviewMarker(`Review stopped: ${label}`);
     return { status: "review-cancelled" };
   }
   const text = (run.stdout || "").trim();
@@ -784,6 +848,7 @@ async function reviewTask({ message, channelId, tool, me, cfg, workspaceMemory,
         ? `I couldn't start \`${cmd}\` to review ${label} — is it installed and on PATH?`
         : `I couldn't get a read on ${label} that time — mention me again to retry the review.`,
     }).catch(() => {});
+    await updateReviewMarker(`Review failed: ${label}`);
     return { status: "review-no-output" };
   }
 
@@ -807,13 +872,399 @@ async function reviewTask({ message, channelId, tool, me, cfg, workspaceMemory,
       parentId: threadRoot,
       body: `I looked at ${label} but couldn't post the review${posted?.error || posted?.message ? `: ${posted.error || posted.message}` : ""}.`,
     }).catch(() => {});
+    await updateReviewMarker(`Review failed: ${label}`);
     return { status: "review-post-failed", error: posted?.error || posted?.message };
   }
   reviewRounds.set(key, rounds + 1);
   console.log(`  review → posted ${verdict} on ${label} (${findings.length} finding(s))`);
+  await updateReviewMarker(`Review ready: ${label}`);
   return { status: "reviewed", verdict, findings: findings.length, prUrl };
 }
 
+/** Render a changed-file list for the folder report card. */
+function renderChangedList({ created, modified, deleted }) {
+  const lines = [];
+  for (const f of created) lines.push(`- added \`${f}\``);
+  for (const f of modified) lines.push(`- changed \`${f}\``);
+  for (const f of deleted) lines.push(`- removed \`${f}\``);
+  return lines.join("\n");
+}
+
+/**
+ * FOLDER MODE (0322). A channel with NO linked GitHub repo but a `folders`
+ * mapping runs the coding CLI directly in that folder and applies changes in
+ * place — it's the user's own machine, same trust as running the CLI themselves.
+ * No branch, no push, no PR, no `gh` — ever. When the folder is a git repo we
+ * snapshot `git status` before/after to report exactly what changed and to offer
+ * a precise revert on reject; a non-git folder gets an honest "can't track / can't
+ * auto-undo" report. The report card drives a decision: approve = keep (already
+ * live), request-changes = re-run in place (bounded), reject = revert the run's
+ * own changes (git repos only).
+ */
+async function handleFolderTask({ message, channelId, tool, me, caps, cfg, deps, signal, parentId, folderPath, brief, workspaceMemory, context }) {
+  void me;
+  const git = deps.git;
+  const tag = requesterTag(message.author);
+  const lead = tag ? `${tag} — ` : "";
+
+  // 1. The mapped folder must actually exist on disk — be honest and actionable.
+  if (!deps.pathExists(folderPath)) {
+    await tool("post_message", {
+      channelId,
+      parentId,
+      body:
+        `I couldn't find the folder \`${folderPath}\` on this machine — it may have moved, been ` +
+        `renamed, or live on a drive that isn't mounted. Fix the path in my \`folders\` config ` +
+        `(or restore the folder), then mention me again.`,
+    });
+    return { status: "no-path" };
+  }
+
+  // 2. Is it a git repo? If so, snapshot the pre-run status so we can (a) report
+  // exactly what the run changed and (b) revert precisely on reject. We NEVER touch
+  // the index (no `git add`), never branch, never push. A non-git folder still runs
+  // — we just can't offer diff/undo.
+  const insideWorkTree = git(folderPath, ["rev-parse", "--is-inside-work-tree"]);
+  const isGit = insideWorkTree.status === 0 && String(insideWorkTree.stdout || "").trim() === "true";
+  const beforeStatus = isGit ? String(git(folderPath, ["status", "--porcelain"]).stdout || "") : "";
+  const dirtyBefore = isGit && beforeStatus.trim() !== "";
+
+  // 3. Instant ack / thread anchor (mirrors the repo flow). When the mention was in
+  // a thread we stay in it; a top-level mention makes the ack the thread anchor so
+  // the run's progress + report card live under it.
+  const ack = await tool("post_message", {
+    channelId,
+    parentId,
+    body: `On it — working directly in \`${folderPath}\`. Changes apply straight to your folder (no branch, no PR); I'll report what changed.`,
+  });
+  const ackId = ack?.messageId ?? null;
+  const threadRoot = parentId ?? ackId;
+
+  // Live progress: reuse the streaming card (post_progress) when the server
+  // supports it, else the edit-in-place heartbeat, else nothing. Kept across
+  // request-changes re-runs on the same status message.
+  let progressId = null;
+  const folderWorking = (elapsedMs, lastLine) => {
+    const base = `Working in \`${folderPath}\` — ${fmtElapsed(elapsedMs)} elapsed. I'll report what changed when it's done.`;
+    const tail = oneLine(lastLine);
+    return tail ? `${base}\n\nLatest: ${tail}` : base;
+  };
+
+  // Run the coding CLI in the folder, streaming progress + honoring timeouts and
+  // the abort signal (reuses runCli via deps + the progress-emitter machinery).
+  const runFolderCli = async (promptText) => {
+    const parts = cfg.codingCmd.split(" ").filter(Boolean);
+    const vendor = detectVendor(cfg.codingCmd);
+    const streamOn = Boolean(caps.postProgress);
+    const streamArgs = streamOn ? codeStreamArgs(vendor) : [];
+    let emitter = null;
+    let progressInflight = Promise.resolve();
+    let stopHeartbeat = () => {};
+    let lastLine = "";
+    // With stream args the CLI's stdout is NDJSON events, not prose — parse it and
+    // keep the final `result` event's summary so the report card gets clean text
+    // (raw stdout would dump JSON into the report). Without stream args, stdout IS
+    // the prose and resultText stays empty.
+    let resultText = "";
+    const resultParser = streamArgs.length ? makeStreamParser(vendor) : null;
+    const foldResultEvents = (events) => {
+      for (const ev of events || []) {
+        if (ev && ev.t === "result" && ev.summary) resultText = ev.summary;
+      }
+    };
+    if (streamOn) {
+      if (!progressId) {
+        try {
+          const r = await tool("post_message", { channelId, parentId: threadRoot, body: folderWorking(0, "") });
+          progressId = r?.messageId ?? null;
+        } catch {
+          progressId = null;
+        }
+      }
+      const statusId = progressId;
+      if (statusId) {
+        emitter = createProgressEmitter({
+          parser: makeStreamParser(vendor),
+          now: deps.now,
+          throttleMs: cfg.progressMs,
+          send: (p) => {
+            try {
+              const r = tool("post_progress", { messageId: statusId, progress: p });
+              if (r && typeof r.then === "function") {
+                const done = r.then(() => {}, () => {});
+                progressInflight = Promise.all([progressInflight, done]).then(() => {}, () => {});
+              }
+            } catch {
+              /* a progress send must never break the run */
+            }
+          },
+        });
+      }
+    } else if (caps.editMessage && cfg.heartbeatMs > 0) {
+      const start = deps.now();
+      let stopped = false;
+      let busy = false;
+      const beat = setInterval(async () => {
+        if (stopped || busy) return;
+        busy = true;
+        const body = folderWorking(deps.now() - start, lastLine);
+        try {
+          if (!progressId) {
+            const r = await tool("post_message", { channelId, parentId: threadRoot, body });
+            progressId = r?.messageId ?? null;
+          } else {
+            await tool("edit_message", { messageId: progressId, body });
+          }
+        } catch {
+          /* a heartbeat must never break the run */
+        } finally {
+          busy = false;
+        }
+      }, cfg.heartbeatMs);
+      if (beat.unref) beat.unref();
+      stopHeartbeat = () => {
+        stopped = true;
+        clearInterval(beat);
+      };
+    }
+    let run;
+    try {
+      run = await deps.runCli({
+        cmd: parts[0],
+        args: [...parts.slice(1), ...streamArgs, memoryPreamble(workspaceMemory) + promptText],
+        cwd: folderPath,
+        timeoutMs: cfg.runTimeoutMs,
+        label: "coding",
+        signal,
+        onData: (c) => {
+          const lines = String(c).split("\n").map((s) => s.trim()).filter(Boolean);
+          if (lines.length) lastLine = lines[lines.length - 1];
+          if (resultParser) {
+            try {
+              foldResultEvents(resultParser.push(String(c)));
+            } catch {
+              /* result extraction must never break the run */
+            }
+          }
+          if (emitter) {
+            try {
+              emitter.feed(c);
+            } catch {
+              /* a progress fold must never break the run */
+            }
+          }
+        },
+      });
+    } finally {
+      stopHeartbeat();
+      if (emitter) {
+        const errored = Boolean(run && (run.aborted || run.error || run.status !== 0));
+        let reason = "";
+        if (errored && run && !run.aborted) {
+          const stderrTail = oneLine((run.stderr || "").trim().split("\n").slice(-3).join(" "), 200);
+          if (run.error?.code === "ENOENT") reason = `Couldn't start ${parts[0]} — is it installed and on PATH?`;
+          else if (run.error?.message) reason = run.error.message;
+          else if (run.status != null) reason = `The CLI exited ${run.status}`;
+          if (stderrTail) reason = reason ? `${reason}: ${stderrTail}` : stderrTail;
+        }
+        try {
+          emitter.done(errored ? "error" : "done", reason);
+        } catch {
+          /* ignore */
+        }
+        try {
+          await progressInflight;
+        } catch {
+          /* a drain failure must never break the run */
+        }
+      }
+    }
+    if (resultParser) {
+      try {
+        foldResultEvents(resultParser.flush());
+      } catch {
+        /* result extraction must never break the run */
+      }
+    }
+    if (run.aborted || signal?.aborted) return { aborted: true };
+    const failed = Boolean(run.error) || run.status !== 0;
+    return {
+      aborted: false,
+      stdout: run.stdout || "",
+      // Clean prose for the report: the stream `result` summary when streaming,
+      // else empty (raw stdout is prose only in the non-streamed case).
+      resultText,
+      streamed: streamArgs.length > 0,
+      failed,
+      errCode: run.error?.code || null,
+      errMessage: run.error?.message || null,
+      status: run.status,
+      stderrTail: oneLine((run.stderr || "").trim().split("\n").slice(-3).join(" "), 300),
+    };
+  };
+
+  // Compute what the run changed (git repos only), vs the pre-run snapshot.
+  const computeChanged = () => {
+    if (!isGit) return { modified: [], created: [], deleted: [] };
+    const afterStatus = String(git(folderPath, ["status", "--porcelain"]).stdout || "");
+    return diffStatusSets(beforeStatus, afterStatus);
+  };
+  const hasChanges = (c) => c.created.length + c.modified.length + c.deleted.length > 0;
+
+  const buildReport = (runResult, changed) => {
+    const changedList = renderChangedList(changed);
+    const stat = isGit ? truncateDiff(String(git(folderPath, ["diff", "--stat"]).stdout || "")).text.trim() : "";
+    // Streamed runs put NDJSON on stdout — use the parsed result summary there;
+    // non-streamed stdout is the agent's prose and is safe to quote.
+    const rawOut = (runResult.resultText || (runResult.streamed ? "" : runResult.stdout) || "").trim();
+    const parts = [`${lead}worked directly in \`${folderPath}\`.`];
+    if (rawOut) parts.push(rawOut.slice(0, 2000));
+    if (isGit) parts.push(changedList ? `Changed files:\n${changedList}` : "No tracked file changes were detected.");
+    if (stat) parts.push("```\n" + stat + "\n```");
+    const caveats = [`Changes were applied directly to ${folderPath} — there is no branch or PR to review.`];
+    if (!isGit) caveats.push("This folder isn't a git repository, so I can't show a file-level diff or automatically undo the changes.");
+    if (dirtyBefore) caveats.push("The folder already had uncommitted local changes before this run — those are mixed in with mine.");
+    if (runResult.failed) {
+      const why = runResult.errMessage ? `: ${runResult.errMessage}` : runResult.status != null ? ` (exit ${runResult.status})` : "";
+      caveats.push(`The coding agent didn't exit cleanly${why} — review the changes carefully.`);
+    }
+    const folderName = folderPath.split("/").filter(Boolean).pop() || folderPath;
+    return { title: `Folder run: ${folderName}`, summary: parts.join("\n\n"), caveats, todos: [] };
+  };
+
+  // --- Run ---
+  let runResult = await runFolderCli(folderTaskPrompt({ message, context, brief, folderPath }));
+  if (runResult.aborted) {
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: Boolean(threadRoot),
+      body: `Stopped — I left \`${folderPath}\` as it was.`,
+    });
+    return { status: "cancelled" };
+  }
+
+  let changed = computeChanged();
+
+  // Honest early exits (no report/decision): a failed run that changed nothing, or
+  // a clean success that changed nothing.
+  if (runResult.failed && (!isGit || !hasChanges(changed))) {
+    let body;
+    if (runResult.errCode === "ENOENT") {
+      body = `I couldn't start \`${cfg.codingCmd}\` — is it installed and on PATH?`;
+    } else {
+      const why = runResult.errMessage
+        ? ` (${runResult.errMessage})`
+        : runResult.status != null
+          ? ` (the CLI exited ${runResult.status})`
+          : "";
+      const tail = runResult.stderrTail ? `: ${runResult.stderrTail}` : "";
+      const left = isGit ? `\`${folderPath}\` is unchanged` : `check \`${folderPath}\` for any partial edits`;
+      body = `The run didn't finish${why}${tail}. ${left} — mention me to retry.`;
+    }
+    await tool("post_message", { channelId, parentId: threadRoot, broadcast: Boolean(threadRoot), body });
+    return { status: "run-failed" };
+  }
+  if (!runResult.failed && isGit && !hasChanges(changed)) {
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: Boolean(threadRoot),
+      body: `The run finished but nothing changed in \`${folderPath}\`. Mention me to try a different approach.`,
+    });
+    return { status: "no-changes" };
+  }
+
+  // --- Report card + decision loop ---
+  const postFolderReport = async (rr, ch) => {
+    const report = buildReport(rr, ch);
+    const res = await tool("post_report", { channelId, parentId: threadRoot, broadcast: true, ...report });
+    return res?.messageId ?? null;
+  };
+  let reportMessageId = await postFolderReport(runResult, changed);
+  let decision = await awaitDecision({ tool, channelId, reportMessageId, cfg, deps, parentId: threadRoot, signal });
+
+  const maxRounds = cfg.maxRounds || 3;
+  let round = 1;
+  while (decision.kind === "changes" && round < maxRounds) {
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      body: `Revising in \`${folderPath}\` with your feedback${decision.note ? `: ${decision.note}` : ""} (round ${round + 1}/${maxRounds}).`,
+    });
+    runResult = await runFolderCli(
+      folderTaskPrompt({ message, context, brief, folderPath }) +
+        `\n\nReviewer feedback to address: ${decision.note || "(see the channel)"}`,
+    );
+    if (runResult.aborted) {
+      await tool("post_message", { channelId, parentId: threadRoot, broadcast: Boolean(threadRoot), body: `Stopped — I left \`${folderPath}\` as it was.` });
+      return { status: "cancelled" };
+    }
+    changed = computeChanged();
+    reportMessageId = await postFolderReport(runResult, changed);
+    decision = await awaitDecision({ tool, channelId, reportMessageId, cfg, deps, parentId: threadRoot, signal });
+    round += 1;
+  }
+
+  // --- Terminal ---
+  if (decision.kind === "approved") {
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: Boolean(threadRoot),
+      body: `${lead}approved — the changes are already live in \`${folderPath}\`.`,
+    });
+    return { status: "folder-done", decision: "approved" };
+  }
+
+  if (decision.kind === "rejected") {
+    if (!isGit) {
+      const all = [...changed.created, ...changed.modified, ...changed.deleted];
+      await tool("post_message", {
+        channelId,
+        parentId: threadRoot,
+        broadcast: Boolean(threadRoot),
+        body:
+          `Rejected — but \`${folderPath}\` isn't a git repository, so I can't automatically undo the changes. ` +
+          (all.length ? `I touched:\n${renderChangedList(changed)}\n\nRevert these by hand.` : `Please review the folder and revert by hand.`),
+      });
+      return { status: "folder-done", decision: "rejected", reverted: false };
+    }
+    // Revert ONLY what the run itself changed: checkout tracked modifications +
+    // deletions, remove untracked files the run created. Never a blanket reset —
+    // pre-existing local changes stay untouched.
+    const trackedToRestore = [...changed.modified, ...changed.deleted];
+    if (trackedToRestore.length) git(folderPath, ["checkout", "--", ...trackedToRestore]);
+    if (changed.created.length) git(folderPath, ["clean", "-fd", "--", ...changed.created]);
+    const revertedList = renderChangedList(changed);
+    await tool("post_message", {
+      channelId,
+      parentId: threadRoot,
+      broadcast: Boolean(threadRoot),
+      body:
+        `Rejected — reverted my changes in \`${folderPath}\`.` +
+        (revertedList ? `\n\nRestored:\n${revertedList}` : "") +
+        (dirtyBefore ? `\n\nYour pre-existing local changes were left untouched.` : ""),
+    });
+    return { status: "folder-done", decision: "rejected", reverted: true };
+  }
+
+  if (decision.kind === "cancelled") {
+    await tool("post_message", { channelId, parentId: threadRoot, broadcast: Boolean(threadRoot), body: `Stopped — the changes so far are still in \`${folderPath}\`.` });
+    return { status: "cancelled" };
+  }
+
+  // Timeout (or a leftover 'changes' past the round cap): note + release, same as
+  // the repo flow.
+  await tool("post_message", {
+    channelId,
+    parentId: threadRoot,
+    broadcast: Boolean(threadRoot),
+    body: `Still awaiting your review of the changes in \`${folderPath}\`. They're already applied — mention me to revise or revert once you've decided.`,
+  });
+  return { status: "folder-done", decision: "timeout" };
+}
+
 /** Handle one task. cfg/deps injectable for tests. `opts.signal` (AbortSignal)
  *  cancels an in-flight run — the queue fires it when a human says "stop". */
 export async function handleTask({ message, channelId, tool, me, caps = {} }, cfg, depsOverride, opts = {}) {
@@ -824,7 +1275,10 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   const parentId = message.parentId ?? null;
 
   const { links = [] } = await tool("get_links", { channelId }).catch(() => ({ links: [] }));
-  const repoLink = links.find((l) => l.repo_full_name);
+  // A folder link (0324) carries the folder PATH in repo_full_name for display —
+  // it is NOT a GitHub repo, so it must never be picked as the channel's repo.
+  // Exclude kind='folder'; pr/branch/repo rows with repo_full_name still count.
+  const repoLink = links.find((l) => l.kind !== "folder" && l.repo_full_name);
   // Workspace memory ("soul") — shared project context the agent should know.
   const { memory: workspaceMemory = null } = await tool("get_workspace_memory", {}).catch(() => ({
     memory: null,
@@ -834,6 +1288,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // crucial: a reply like "yeah, do it" only means something against what was
   // just said.
   const context = await fetchContext({ channelId, tool, parentId });
+  const mode = agentMode(message);
 
   // REVIEW EXECUTION (0288): a review-request routes to the read-only reviewer
   // BEFORE the chat/code flow — it reads the PR's diff and posts an advisory review
@@ -863,13 +1318,67 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     }
   }
 
-  // No repo linked → nothing to build; just reply.
+  // No repo linked → either FOLDER mode (0322: a channel mapped to a plain local
+  // folder can still get coding work done) or, failing that, just reply. A linked
+  // repo always wins — the folder map is only consulted when there's no repo link.
   if (!repoLink) {
+    const folderPath = resolveFolderPath(cfg, channelId);
+    if (folderPath) {
+      // Same chat-vs-code decision the repo path uses: mode 'ask'/'ship' short-
+      // circuit exactly as in the repo flow, otherwise the LLM router judges intent
+      // (its CLI call goes through deps.runCli so folder mode is unit-testable).
+      const routed =
+        mode === "ask"
+          ? { code: false, reply: null }
+          : mode === "ship"
+            ? { code: true, task: message.body }
+            : await routeIntent({
+                name: me?.agentName || "an assistant",
+                repoFullName: folderPath,
+                transcript: context.transcript,
+                workspaceMemory,
+                cfg,
+                signal,
+                runCliFn: deps.runCli,
+              });
+      if (routed.aborted || signal?.aborted) {
+        await tool("post_message", { channelId, parentId, body: "Stopped." });
+        return { status: "chat" };
+      }
+      if (routed.code) {
+        return await handleFolderTask({
+          message,
+          channelId,
+          tool,
+          me,
+          caps,
+          cfg,
+          deps,
+          signal,
+          parentId,
+          folderPath,
+          brief: routed.task,
+          workspaceMemory,
+          context,
+        });
+      }
+      // Not a coding task → post the router's reply if it produced one, else fall
+      // through to a normal conversational reply.
+      if (routed.reply) {
+        await tool("post_message", { channelId, parentId, body: routed.reply });
+        return { status: "chat" };
+      }
+    }
     await respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps });
     return { status: "chat" };
   }
   const repoFullName = repoLink.repo_full_name;
 
+  if (mode === "ask") {
+    await respondConversationally({ message, channelId, tool, me, cfg, repoLink, parentId, workspaceMemory, signal, context, caps });
+    return { status: "chat" };
+  }
+
   // Same-PR follow-up (0281): if this mention is a reply in a thread that already
   // owns a run (branch + PR), we may continue THAT run instead of forking a
   // duplicate. Look it up by the thread root — the parentId the reply carried.
@@ -896,15 +1405,18 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // signal is only ever acted on when the PR is open (resolveFollowupMode → 'new'
   // otherwise), so telling the router the thread "owns an open PR" when the run is
   // merged/closed would just mislead the model and waste a classification.
-  const routed = await routeIntent({
-    name: me?.agentName || "an assistant",
-    repoFullName,
-    transcript: context.transcript,
-    workspaceMemory,
-    cfg,
-    signal,
-    hasActiveRun: activeRunOpen,
-  });
+  const routed =
+    mode === "ship"
+      ? { code: true, task: message.body, followupSignal: null }
+      : await routeIntent({
+          name: me?.agentName || "an assistant",
+          repoFullName,
+          transcript: context.transcript,
+          workspaceMemory,
+          cfg,
+          signal,
+          hasActiveRun: activeRunOpen,
+        });
   if (routed.aborted || signal?.aborted) {
     await tool("post_message", { channelId, parentId, body: "Stopped." });
     return { status: "chat" };
@@ -1108,6 +1620,10 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // The ack itself stays top-level (the channel-visible "on it"); terminal
   // outcomes + report cards broadcast back to the channel from the thread.
   const threadRoot = parentId ?? ackId;
+  const updateChannelMarker = async (body) => {
+    if (!ackId || parentId || !body) return;
+    await tool("edit_message", { messageId: ackId, body }).catch(() => {});
+  };
   // Bind this run to the thread root (0279/0280), now follow-up-aware (0281):
   //   iterate  → REUSE the thread's existing run (don't record a second one); the
   //              same PR updates in place and its status stays awaiting_review.
@@ -1491,14 +2007,16 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   // Post the right cancel message: honest about whether cleanup actually worked.
   const postStopped = async () => {
     const clean = discardBranch();
+    const body = clean
+      ? `Stopped — discarded \`${branch}\`.`
+      : `Stopped, but couldn't fully clean \`${branch}\` — run \`git reset --hard && git switch ${startRef.ref || cfg.defaultBranch}\` in ${repoPath}.`;
     await tool("post_message", {
       channelId,
       parentId: threadRoot,
       broadcast: true,
-      body: clean
-        ? `Stopped — discarded \`${branch}\`.`
-        : `Stopped, but couldn't fully clean \`${branch}\` — run \`git reset --hard && git switch ${startRef.ref || cfg.defaultBranch}\` in ${repoPath}.`,
+      body,
     });
+    await updateChannelMarker(compactRunMarker("cancelled", branch));
     return { status: "cancelled", branch };
   };
 
@@ -1511,6 +2029,12 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   let teamMemoryBlock = "";
   if (caps.recall) {
     try {
+      // Pass the task's channelId so the server scopes recall to this project AND
+      // can apply the guest gate (0298): the daemon's token is long-lived with no
+      // bound channel, so the server relies on this per-call channelId to decide
+      // whether a guest is present. Residual: a recall that omits channelId can't
+      // be guest-gated server-side (no channel to check) — the daemon always
+      // passes it here, so that path is covered.
       const recalled = await tool("recall", { channelId, limit: 20 }).catch(() => null);
       const mems = Array.isArray(recalled?.memories) ? recalled.memories : [];
       teamMemoryBlock = buildMemoryBlock(mems);
@@ -1559,6 +2083,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
           `re-mention me to ship or discard.`,
       });
       await finalizeProgress(`\`${branch}\` has the agent's own commits — needs review.`);
+      await updateChannelMarker(compactRunMarker("changes", branch));
       return { status: "self-committed-gated", branch };
     }
     // When a live status card was streaming, settle the report onto it (0289) —
@@ -1580,6 +2105,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       runId,
     });
     await recordSession(selfResult.prUrl);
+    await updateChannelMarker(compactRunMarker(selfResult.status, selfResult.branch));
     return selfResult;
   }
   if (staged.empty) {
@@ -1613,6 +2139,9 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
       git(repoPath, ["switch", "-"]);
       git(repoPath, ["branch", "-D", branch]);
     }
+    await updateChannelMarker(
+      compactRunMarker(staged.failed ? "run-failed" : "no-changes", branch),
+    );
     return { status: staged.failed ? "run-failed" : "no-changes" };
   }
 
@@ -1627,7 +2156,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // message. Only the DEFAULT gate:false report settles in place; gate:true's
     // proposal → decision → report lifecycle stays on separate messages (a
     // separate ticket). No status card (older server / status post failed) →
-    // settleId is null and applyDecision posts a fresh broadcast report as before.
+    // settleId is null and applyDecision posts a fresh final report instead.
     const settleId = streamOn && progressId ? progressId : null;
     const result = await applyDecision({
       decision: { kind: "approved" },
@@ -1653,6 +2182,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
     // Re-record with the now-known PR url so the local session record + the run row
     // carry the PR the session belongs to (best-effort; session id unchanged).
     await recordSession(result.prUrl);
+    await updateChannelMarker(compactRunMarker(result.status, result.branch));
     return { ...result, stat: staged.stat, sessionId: runSessionId };
   }
 
@@ -1707,6 +2237,7 @@ export async function handleTask({ message, channelId, tool, me, caps = {} }, cf
   });
   await finalizeProgress(`Done on \`${branch}\` — see the report below.`);
   await recordSession(result.prUrl);
+  await updateChannelMarker(compactRunMarker(result.status, result.branch));
   return { ...result, reportMessageId: proposal.reportMessageId, stat: proposal.stat, rounds: round, sessionId: runSessionId };
   } finally {
     // Whatever happened, give the user their uncommitted work back.