agentus 0.1.0 → 0.3.0

package/packages/server/src/acp/session-manager.ts

@@ -209,10 +209,17 @@ export class SessionManager {
     // one you come back to, even when it is the oldest row in the list.
     const lastAt = this.#store.lastActivityAt();
     return [...this.#sessions.values()]
+      // An ARCHIVED session is not 工作空间 material, whatever its process is doing (resume leaves the
+      // flag alone, so a restored-then-archived slot can be live). It is listed by `archived()`
+      // instead — one row in one bucket, or the rail shows the same slot twice.
+      .filter((s) => this.#store.getSession(s.info.id)?.archivedAt == null)
       .map((s) => ({
         ...s.info,
         lastSeq: this.#store.maxSeq(s.info.id),
         lastAt: lastAt.get(s.info.id) ?? s.info.createdAt,
+        archivedAt: null,
+        // a row in the manager's map has a process, by definition
+        cold: false,
       }))
       .sort((a, b) => (b.lastAt ?? 0) - (a.lastAt ?? 0) || b.createdAt - a.createdAt);
   }
@@ -416,6 +423,11 @@ export class SessionManager {
       live.info.models = readModels(res);
       // the row just proved itself: remember that, plus what the agent said it can do
       this.#noteBackendCheck(String(backend), { ok: true, latencyMs: Date.now() - spawnStarted }, handshakeFrom(init, res));
+      // The row's DEFAULT permission mode, applied HERE: on a brand-new session, before the first
+      // prompt. Hermes reads its mode through a live getter (acp_adapter/server.py `policy_getter`),
+      // so the very first turn is already governed by it. A later `resume()` never passes through
+      // this method — that is exactly what keeps a per-session pick from being silently undone.
+      await this.#applyDefaultMode(live);
       this.#updateSession(live);
       return live.info;
     } catch (err) {
@@ -699,33 +711,74 @@ export class SessionManager {
     });
   }
 
-  /** Sessions we know about on disk but have no process for (rail's cold slots). */
-  archived(limit = 20): SessionInfo[] {
+  /** Rows the OPERATOR put away — 已归档. Chosen by the archive FLAG, not by liveness: a session
+   *  the operator archived belongs there whatever its process is doing, and a session that merely
+   *  lost its process (crashed, was closed, or was reaped for being idle) does NOT — that was the
+   *  old rule, and it turned 已归档 into a drawer where the operator's own intent was
+   *  indistinguishable from debris.
+   *
+   *  No cap: this list is curated by hand, so hiding its tail would hide the operator's own work.
+   *  Real removal is the ✕ purge button (DELETE on a cold row). */
+  archived(): SessionInfo[] {
+    const lastAtAll = this.#store.lastActivityAt();
     return this.#store
-      // include closed rows: "close" means "kill the process, keep the transcript as a cold
-      // slot" (that is what the UI's close prompt promises) — filtering status!='closed' made
-      // the slot vanish from the rail entirely, leaving the transcript unreachable even though
-      // it was still on disk. Real deletion is the separate ✕ purge button.
       .listSessions(true)
-      .filter((r) => !this.#sessions.has(r.id))
-      .map((r) => ({
-        id: r.id, backend: r.backend, acpSessionId: r.acpSessionId, cwd: r.cwd,
-        workspace: r.workspace ?? null,
-        models: (r.models ?? null) as SessionInfo["models"],
-        contextLimit: r.contextLimit ?? null,
-        title: r.title, autoTitle: r.autoTitle ?? null, status: r.status, pid: null, createdAt: r.createdAt,
-        modes: (r.modes ?? null) as SessionModeState | null,
-        configOptions: (r.configOptions ?? []) as ConfigOptionView[],
-        usage: (r.usage ?? null) as SessionInfo["usage"],
-        commands: normCommands(r.commands),
-        lastSeq: this.#store.maxSeq(r.id),
-        lastAt: this.#store.lastActivityAt().get(r.id) ?? r.createdAt,
-      }))
+      .filter((r) => r.archivedAt != null)
+      .map((r) => {
+        const live = this.#sessions.get(r.id);
+        // An archived row can still have a process — resume does not touch the flag — and then it is
+        // NOT cold: the rail must draw a live row (and clicking it hands over the floor rather than
+        // waking anything), or the operator is told a slot is asleep while it is running.
+        return live
+          ? {
+              ...live.info,
+              lastSeq: this.#store.maxSeq(r.id),
+              lastAt: lastAtAll.get(r.id) ?? r.createdAt,
+              archivedAt: r.archivedAt ?? null,
+              cold: false,
+            }
+          : this.#infoFromRow(r);
+      })
+      .sort((a, b) => (b.archivedAt ?? 0) - (a.archivedAt ?? 0) || (b.lastAt ?? 0) - (a.lastAt ?? 0));
+  }
+
+  /** Cold rows that are NOT archived: on disk, no process, still part of 工作空间. A crashed slot,
+   *  one the operator closed, or one THIS cockpit reaped for being idle — all of them must stay
+   *  reachable in the rail (the old rule showed them under 已归档; the older one dropped them out of
+   *  the list entirely, which is how a transcript became unreachable while still on disk).
+   *
+   *  Capped, unlike `archived()`: crash debris accumulates without anyone choosing it, and the rail
+   *  has its own recent-N rule anyway. */
+  cold(limit = 20): SessionInfo[] {
+    return this.#store
+      .listSessions(true)
+      .filter((r) => r.archivedAt == null && !this.#sessions.has(r.id))
+      .map((r) => this.#infoFromRow(r))
       // cold rows by the same rule as live ones (recent chat first), THEN take the page
       .sort((a, b) => (b.lastAt ?? 0) - (a.lastAt ?? 0) || b.createdAt - a.createdAt)
       .slice(0, limit);
   }
 
+  /** One row in the shape list()/cold()/archived() produce, from a stored row. */
+  #infoFromRow(r: SessionRow): SessionInfo {
+    return {
+      id: r.id, backend: r.backend, acpSessionId: r.acpSessionId, cwd: r.cwd,
+      workspace: r.workspace ?? null,
+      models: (r.models ?? null) as SessionInfo["models"],
+      contextLimit: r.contextLimit ?? null,
+      title: r.title, autoTitle: r.autoTitle ?? null, status: r.status, pid: null, createdAt: r.createdAt,
+      modes: (r.modes ?? null) as SessionModeState | null,
+      configOptions: (r.configOptions ?? []) as ConfigOptionView[],
+      usage: (r.usage ?? null) as SessionInfo["usage"],
+      commands: normCommands(r.commands),
+      lastSeq: this.#store.maxSeq(r.id),
+      lastAt: this.#store.lastActivityAt().get(r.id) ?? r.createdAt,
+      archivedAt: r.archivedAt ?? null,
+      // no process by construction: this path only ever runs for a row that is not in the map
+      cold: true,
+    };
+  }
+
   async prompt(
     sessionId: string,
     text: string,
@@ -827,6 +880,47 @@ export class SessionManager {
     await s.conn.cancel({ sessionId: s.info.acpSessionId }).catch(() => {});
   }
 
+  /**
+   * Put a NEW session into its backend row's default permission mode (BackendRow.defaultMode).
+   * Called from `create()` only — see the call site for why a resume must never do this.
+   *
+   * Three refusals are deliberate:
+   *  · a row with no default sends NOTHING (the agent keeps its own default) — so a registry the
+   *    operator never touched behaves exactly as it did before this existed;
+   *  · a mode the agent did not advertise is not sent either: it would come back as a refusal nobody
+   *    sees, and the settings row already wears a warning saying the pick does not match this
+   *    agent's handshake (registry.rowWarnings);
+   *  · a failure NEVER fails the slot. The session is usable, just in the agent's own mode — and the
+   *    log line is the only evidence of which of those two happened, so it is not optional.
+   */
+  async #applyDefaultMode(live: LiveSession): Promise<void> {
+    const wanted = (this.#store.getBackend(String(live.info.backend))?.defaultMode ?? "").trim();
+    if (!wanted) return;
+    const modes = live.info.modes;
+    const acpSessionId = live.info.acpSessionId;
+    if (!modes || !live.conn || !acpSessionId) return;
+    const ids = (modes.availableModes ?? []).map((m) => m.id);
+    if (!ids.includes(wanted)) {
+      console.log(
+        `[agentus] session ${live.info.id}: default permission mode "${wanted}" is not advertised by ` +
+          `${String(live.info.backend)} (${ids.join(", ") || "no modes"}) — sending nothing`,
+      );
+      return;
+    }
+    if (modes.currentModeId === wanted) return;
+    try {
+      await live.conn.setSessionMode({ sessionId: acpSessionId, modeId: wanted });
+      live.info.modes = { ...modes, currentModeId: wanted };
+      console.log(`[agentus] session ${live.info.id}: default permission mode -> ${wanted}`);
+    } catch (e) {
+      // qodercli advertises modes but answered -32601 in the design probe, so "advertised but not
+      // implemented" is a real case — same tolerance as setMode(), and never a failed spawn.
+      console.log(
+        `[agentus] session ${live.info.id}: default permission mode "${wanted}" not applied: ${errMessage(e)}`,
+      );
+    }
+  }
+
   async setMode(sessionId: string, modeId: string): Promise<void> {
     const s = this.#need(sessionId);
     if (!s.conn || !s.info.acpSessionId) throw new Error("session not ready");
@@ -1107,17 +1201,87 @@ export class SessionManager {
 
   async closeSession(sessionId: string): Promise<void> {
     const s = this.#need(sessionId);
-    for (const { resolve, timer } of s.pendingPermissions.values()) {
+    this.#stop(s, "closed");
+    this.#emitSessions();
+  }
+
+  /** 归档 / 取消归档 — the operator's own STORAGE decision, taken independently of the process.
+   *
+   *  Archiving a LIVE session stops its process too: 「我把它收起来了」 and 「它还在后台吃内存」
+   *  contradict each other, and demanding a close first would make the archive a two-step ritual that
+   *  says nothing about intent. Un-archiving only moves the flag — the row lands back in 工作空间 as
+   *  a cold slot, and the rail's 「取消归档并恢复」 wakes it with a separate resume (so a restore that
+   *  fails to load leaves a visible cold slot rather than an error nobody asked for). */
+  async setArchived(id: string, on: boolean): Promise<SessionInfo> {
+    const live = this.#sessions.get(id);
+    const row = this.#store.getSession(id);
+    if (!row) throw new Error(`no such session: ${id}`);
+    if (on && live) this.#stop(live, "archived");
+    this.#store.setArchived(id, on ? Date.now() : null);
+    this.#emitSessions();
+    return this.#sessions.get(id)?.info ?? this.#coldInfo(id);
+  }
+
+  /** Stop a slot's agent process and record WHY it went away. The row always survives with its
+   *  transcript: the transcript is the operator's, the process is ours to reclaim.
+   *
+   *  `reaped` is its own status on purpose — 「它怎么变冷了」 has three different answers (I closed
+   *  it / it crashed / the cockpit reclaimed it for being idle) and a rail that shows one word for
+   *  all three teaches the operator to distrust the column. */
+  #stop(live: LiveSession, why: "closed" | "archived" | "reaped"): void {
+    for (const { resolve, timer } of live.pendingPermissions.values()) {
       clearTimeout(timer);
       resolve({ outcome: { outcome: "cancelled" } });
     }
-    s.pendingPermissions.clear();
-    s.child?.kill("SIGTERM");
-    s.info.status = "closed";
-    const row = this.#store.getSession(sessionId);
-    if (row) this.#store.upsertSession({ ...row, status: "closed", closedAt: Date.now(), pid: null });
-    this.#sessions.delete(sessionId);
-    this.#emitSessions();
+    live.pendingPermissions.clear();
+    live.child?.kill("SIGTERM");
+    live.info.status = why === "reaped" ? "reaped" : "closed";
+    live.info.pid = null;
+    const row = this.#store.getSession(live.info.id);
+    if (row) {
+      this.#store.upsertSession({
+        ...row, status: live.info.status, closedAt: Date.now(), pid: null,
+      });
+    }
+    this.#sessions.delete(live.info.id);
+  }
+
+  /** Reclaim idle slots: stop the agent process of a session nobody has touched for the operator's
+   *  threshold. Deliberately NOT an archive — the row stays in 工作空间 wearing `reaped` and a click
+   *  brings it back. AionUi ships exactly this switch (设置 → 系统 → 「Agent 空闲超时（分钟）」,
+   *  default 5, 1–60) and the guards below are what its changelog had to add after the first version
+   *  killed agents that were still working: never touch a slot mid-turn, one waiting on a human, or
+   *  one the operator is WATCHING right now (a reply that lands while he reads it must not be killed
+   *  under him).
+   *
+   *  `idleMs()` is read on every tick, so a settings change applies with no restart; 0 = off. */
+  startIdleReaper(opts: { idleMs: () => number; watched?: (id: string) => boolean; intervalMs?: number }): () => void {
+    const interval = opts.intervalMs ?? 30_000;
+    const tick = (): void => {
+      const idleMs = opts.idleMs();
+      if (!(idleMs > 0)) return;
+      const now = Date.now();
+      let reaped = 0;
+      for (const s of [...this.#sessions.values()]) {
+        if (s.busy || s.pendingPermissions.size) continue;
+        if (s.info.status === "starting" || s.info.status === "running") continue;
+        if (opts.watched?.(s.info.id)) continue;
+        const lastAt = s.info.lastAt ?? s.info.createdAt;
+        if (now - lastAt < idleMs) continue;
+        console.log(
+          `[agentus] idle reap: ${s.info.id} (${Math.round((now - lastAt) / 60_000)} min idle, limit ${Math.round(idleMs / 60_000)} min)`,
+        );
+        this.#stop(s, "reaped");
+        reaped += 1;
+      }
+      // Only speak when something changed: a frame every tick would be noise on the socket (and on
+      // the phone's notification path, which observes this same stream).
+      if (reaped) this.#emitSessions();
+    };
+    const timer = setInterval(tick, interval);
+    // A server that will not exit because of the reclaim timer is a worse bug than the memory it saves.
+    timer.unref?.();
+    return () => clearInterval(timer);
   }
 
   /** The list every client needs to be current: the rows PLUS what is already waiting for an
@@ -1689,22 +1853,14 @@ export class SessionManager {
     this.#store.touchActivity(live.info.id, at);
   }
 
-  /** One cold row, in the same shape list()/archived() produce. */
+  /** One cold row, in the same shape list()/cold()/archived() produce. */
   #coldInfo(id: string): SessionInfo {
     const r = this.#store.getSession(id);
     if (!r) throw new Error(`no such session: ${id}`);
     return {
-      id: r.id, backend: r.backend, acpSessionId: r.acpSessionId, cwd: r.cwd,
-      workspace: r.workspace ?? null, contextLimit: r.contextLimit ?? null,
+      ...this.#infoFromRow(r),
+      // the one difference from the list path: the model's own window, which the resume card prints
       modelContextLimit: this.#store.getModelLimit(((r.models ?? null) as SessionInfo["models"])?.currentModelId ?? null),
-      models: (r.models ?? null) as SessionInfo["models"],
-      title: r.title, autoTitle: r.autoTitle ?? null, status: r.status, pid: null, createdAt: r.createdAt,
-      modes: (r.modes ?? null) as SessionModeState | null,
-      configOptions: (r.configOptions ?? []) as ConfigOptionView[],
-      usage: (r.usage ?? null) as SessionInfo["usage"],
-      commands: normCommands(r.commands),
-      lastSeq: this.#store.maxSeq(id),
-      lastAt: this.#store.lastActivityAt().get(id) ?? r.createdAt,
     };
   }
 
@@ -1748,6 +1904,8 @@ export class SessionManager {
       pid: null,
       createdAt: now,
       closedAt: null,
+      // a fork is a NEW conversation: it is nobody's archive (the parent's flag is not inherited)
+      archivedAt: null,
       // the agent just told us the fork's modes/options — keep them so the new slot shows
       // the right permission mode and thinking depth before it is even resumed
       modes: res?.modes ?? source.info.modes ?? null,
@@ -1798,6 +1956,9 @@ function sessionRow(i: SessionInfo, home: string | null = null) {
   return {
     id: i.id, backend: i.backend, acpSessionId: i.acpSessionId, cwd: i.cwd,
     title: i.title, status: i.status, pid: i.pid, createdAt: i.createdAt, closedAt: null,
+    // never written by this upsert (the archive flag has its own statement — see setArchived):
+    // carried here only so the row type stays honest.
+    archivedAt: i.archivedAt ?? null,
     modes: i.modes ?? null, configOptions: i.configOptions ?? [],
     usage: i.usage ?? null, commands: i.commands ?? [],
     models: i.models ?? null,

package/packages/server/src/fs.ts

@@ -4,6 +4,7 @@
 // product), so this adds no new power — it just makes the choice discoverable instead
 // of demanding a path typed from memory. Listing is deliberately narrow: directories
 // only, one level at a time, capped, and never followed through symlinks we cannot stat.
+import crypto from "node:crypto";
 import fs from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
@@ -125,12 +126,219 @@ export interface FilePreview {
   truncated: boolean;
   /** looks like binary: the panel shows a "cannot preview" note instead of mojibake */
   binary: boolean;
+  /** how the panel should draw it (see FileKind) */
+  kind: FileKind;
+  contentType: string;
+  mtimeMs: number;
+  /** sha1 of the bytes on disk: the editor hands this back on save so a rewrite the agent made
+   *  while the operator was typing is refused instead of silently overwritten */
+  hash: string;
+  editable: boolean;
+}
+
+/** What the panel should DRAW for a file. Decided here, once, so the browser does not carry a
+ *  second extension table that can drift from this one. */
+export type FileKind =
+  | "markdown" | "image" | "pdf" | "html" | "csv" | "code" | "text"
+  | "audio" | "video" | "office" | "archive" | "binary";
+
+const KIND_BY_EXT: Record<string, FileKind> = {
+  md: "markdown", markdown: "markdown", mdx: "markdown",
+  png: "image", jpg: "image", jpeg: "image", gif: "image", webp: "image", avif: "image",
+  bmp: "image", ico: "image", svg: "image", tiff: "image", heic: "image",
+  pdf: "pdf",
+  html: "html", htm: "html",
+  csv: "csv", tsv: "csv",
+  // languages the panel can syntax-highlight (the web side has the hljs set; anything not
+  // listed still renders as text, which is the honest outcome)
+  js: "code", mjs: "code", cjs: "code", jsx: "code", ts: "code", tsx: "code", json: "code",
+  py: "code", rb: "code", go: "code", rs: "code", java: "code", c: "code", h: "code",
+  cpp: "code", cc: "code", hpp: "code", cs: "code", php: "code", swift: "code", kt: "code",
+  sh: "code", bash: "code", zsh: "code", fish: "code", ps1: "code",
+  css: "code", scss: "code", less: "code", sql: "code", yml: "code", yaml: "code",
+  toml: "code", ini: "code", conf: "code", env: "code", xml: "code", plist: "code",
+  dockerfile: "code", gitignore: "code", patch: "code", diff: "code",
+  txt: "text", log: "text", text: "text", lock: "text",
+  mp3: "audio", wav: "audio", ogg: "audio", m4a: "audio", flac: "audio", aac: "audio", opus: "audio",
+  mp4: "video", webm: "video", mov: "video", mkv: "video", m4v: "video",
+  docx: "office", doc: "office", xlsx: "office", xls: "office", pptx: "office", ppt: "office",
+  odt: "office", ods: "office", odp: "office", rtf: "office",
+  zip: "archive", tar: "archive", gz: "archive", bz2: "archive", xz: "archive", "7z": "archive",
+};
+
+const MIME_BY_EXT: Record<string, string> = {
+  png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp",
+  avif: "image/avif", bmp: "image/bmp", ico: "image/x-icon", svg: "image/svg+xml",
+  tiff: "image/tiff", heic: "image/heic",
+  pdf: "application/pdf",
+  html: "text/html; charset=utf-8", htm: "text/html; charset=utf-8",
+  css: "text/css; charset=utf-8", js: "text/javascript; charset=utf-8",
+  mjs: "text/javascript; charset=utf-8", json: "application/json; charset=utf-8",
+  xml: "application/xml; charset=utf-8", svgz: "image/svg+xml",
+  mp3: "audio/mpeg", wav: "audio/wav", ogg: "audio/ogg", m4a: "audio/mp4", flac: "audio/flac",
+  aac: "audio/aac", opus: "audio/opus",
+  mp4: "video/mp4", webm: "video/webm", mov: "video/quicktime", mkv: "video/x-matroska", m4v: "video/mp4",
+  txt: "text/plain; charset=utf-8", md: "text/markdown; charset=utf-8",
+  csv: "text/csv; charset=utf-8", tsv: "text/tab-separated-values; charset=utf-8",
+  zip: "application/zip", gz: "application/gzip", tar: "application/x-tar",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
+
+/** Extension of a path, lowercased, without the dot. Dotfiles like `.env` report `env`. */
+function extOf(target: string): string {
+  return path.extname(target).replace(/^\./, "").toLowerCase() || path.basename(target).replace(/^\./, "").toLowerCase();
+}
+
+export function fileKind(target: string): FileKind {
+  return KIND_BY_EXT[extOf(target)] ?? "text"; // unknown extensions are shown as text, never refused
+}
+
+/** Only ever used for `inline` preview; unknown types fall back to a neutral binary type
+ *  rather than a wrong one, so the browser does not try to parse e.g. a .dmg as HTML. */
+export function contentTypeFor(target: string): string {
+  return MIME_BY_EXT[extOf(target)] ?? "application/octet-stream";
+}
+
+export interface FileStatInfo {
+  path: string;
+  name: string;
+  /** what the panel should draw for this file (one table, see KIND_BY_EXT) */
+  kind: FileKind;
+  contentType: string;
+  size: number;
+  mtimeMs: number;
+  hash: string;
+  /** the file kind is editable in the panel (text-ish only; binaries are not) */
+  editable: boolean;
+}
+
+const EDITABLE: ReadonlySet<FileKind> = new Set<FileKind>(["markdown", "text", "code", "csv", "html"]);
+
+function statOrThrow(target: string): fs.Stats {
+  try {
+    return fs.statSync(target);
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") throw new FsError(`no such file: ${target}`, "not_found");
+    if (code === "EACCES") throw new FsError(`permission denied: ${target}`, "permission_denied");
+    throw new FsError(`cannot read ${target}: ${code ?? String(e)}`, "bad_path");
+  }
+}
+
+/** sha1 of the file's bytes. Doubles as the "did the file change under the editor?" check, so
+ *  a save can refuse to clobber a rewrite the agent made while the operator was typing. */
+export function fileHash(target: string): string {
+  const h = crypto.createHash("sha1");
+  const fd = fs.openSync(target, "r");
+  try {
+    const buf = Buffer.alloc(64 * 1024);
+    for (;;) {
+      const n = fs.readSync(fd, buf, 0, buf.length, null);
+      if (!n) break;
+      h.update(buf.subarray(0, n));
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return h.digest("hex");
+}
+
+/** Everything the panel needs to decide HOW to draw a file, without reading its bytes. */
+export function statFile(input: string | null | undefined): FileStatInfo {
+  const target = expandPath(input);
+  const st = statOrThrow(target);
+  if (st.isDirectory()) throw new FsError(`not a file: ${target}`, "not_a_file");
+  const kind = fileKind(target);
+  return {
+    path: target,
+    name: path.basename(target),
+    kind,
+    contentType: contentTypeFor(target),
+    size: st.size,
+    mtimeMs: st.mtimeMs,
+    hash: fileHash(target),
+    editable: EDITABLE.has(kind),
+  };
+}
+
+export interface WriteResult {
+  path: string;
+  size: number;
+  mtimeMs: number;
+  hash: string;
+}
+
+const MAX_WRITE_BYTES = 8 * 1024 * 1024;
+
+/** Save a text file the operator edited in the panel.
+ *
+ *  Deliberate limits: the file must ALREADY exist (this is an editor for files the agent and
+ *  the operator are looking at, not a way to create them — a chat window should not be able to
+ *  drop new files anywhere the process can write), it must be a text-ish kind, and it must fit
+ *  in memory. The write goes through a temp file + rename so a crash mid-save cannot leave a
+ *  half-written file where an agent might read it; mode is carried over from the original.
+ *
+ *  `ifHash` is the hash the editor loaded. When it no longer matches, the agent changed the
+ *  file while the operator was typing: a 409 with the current bytes beats silently losing
+ *  either side's work. */
+export function writeTextFile(
+  input: string | null | undefined,
+  content: string,
+  opts: { ifHash?: string } = {},
+): WriteResult {
+  const target = expandPath(input);
+  const st = statOrThrow(target);
+  if (st.isDirectory()) throw new FsError(`not a file: ${target}`, "not_a_file");
+  const kind = fileKind(target);
+  if (!EDITABLE.has(kind)) {
+    throw new FsError(`not an editable file: ${path.basename(target)} (${kind})`, "not_a_file");
+  }
+  const bytes = Buffer.from(content, "utf8");
+  if (bytes.length > MAX_WRITE_BYTES) {
+    throw new FsError(`content too large (${bytes.length} > ${MAX_WRITE_BYTES})`, "bad_path");
+  }
+  const before = opts.ifHash ? fileHash(target) : "";
+  if (opts.ifHash && opts.ifHash !== before) {
+    const cur = readTextFile(target);
+    throw new ChangedOnDiskError(target, before, cur.content, cur.truncated);
+  }
+  const tmp = `${target}.agentus-${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(tmp, bytes, { mode: st.mode & 0o7777 });
+    fs.renameSync(tmp, target);
+  } catch (e) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* the temp file may never have existed */ }
+    throw new FsError(`cannot write ${target}: ${String((e as NodeJS.ErrnoException).code ?? e)}`, "bad_path");
+  }
+  const after = fs.statSync(target);
+  return { path: target, size: after.size, mtimeMs: after.mtimeMs, hash: fileHash(target) };
+}
+
+/** The operator's buffer is based on bytes that no longer exist on disk. Carries the CURRENT
+ *  content so the panel can offer "reload theirs" without a second round trip. */
+export class ChangedOnDiskError extends FsError {
+  constructor(
+    readonly target: string,
+    readonly currentHash: string,
+    readonly currentContent: string,
+    readonly truncated: boolean,
+  ) {
+    super("changed_on_disk", "bad_path");
+  }
 }
 
 const DEFAULT_PREVIEW_BYTES = 256 * 1024;
 
-/** Read a file for the workspace panel. Read-only on purpose: this panel is a
- *  browser, not an editor — writing files is the agent's job, not the cockpit's. */
+/** Read a file for the workspace panel.
+ *
+ *  This used to be read-only on the reasoning that "writing files is the agent's job, not the
+ *  cockpit's". The operator overruled that (2026-10-09: 「可编辑一起搞吧」) and it is his call — a
+ *  cockpit where he can fix a line of markdown without leaving for an editor is the point. So
+ *  the read now also reports what the panel needs to EDIT safely (`hash`, `editable`), and
+ *  `writeTextFile` below does the saving. Reading is still capped and still refuses to guess at
+ *  binaries. */
 export function readTextFile(input: string, opts: { maxBytes?: number } = {}): FilePreview {
   const target = expandPath(input);
   const maxBytes = Math.max(1024, opts.maxBytes ?? DEFAULT_PREVIEW_BYTES);
@@ -151,6 +359,7 @@ export function readTextFile(input: string, opts: { maxBytes?: number } = {}): F
     fs.readSync(fd, buf, 0, len, 0);
     // A NUL byte in the first 8KB is the classic binary tell.
     const binary = buf.subarray(0, Math.min(buf.length, 8192)).includes(0);
+    const kind = fileKind(target);
     return {
       path: target,
       name: path.basename(target),
@@ -158,6 +367,11 @@ export function readTextFile(input: string, opts: { maxBytes?: number } = {}): F
       content: binary ? "" : buf.toString("utf8"),
       truncated: st.size > len,
       binary,
+      kind,
+      contentType: contentTypeFor(target),
+      mtimeMs: st.mtimeMs,
+      hash: fileHash(target),
+      editable: EDITABLE.has(kind),
     };
   } finally {
     fs.closeSync(fd);