@runuai/host 0.2.6 → 0.3.0

package/db/migrations/0007_host_github_token_kind.sql

@@ -0,0 +1,7 @@
+-- ADR-033: non-expiring per-host tokens. `kind` distinguishes the stored token:
+--   'refresh' (legacy, ADR-027) → refresh_token_ct holds a refresh token; the
+--             host exchanges it for short-lived access tokens.
+--   'access'  (ADR-033)         → refresh_token_ct holds a long-lived, non-
+--             expiring access token; injected directly, no exchange/refresh.
+-- Existing rows default to 'refresh' (their current semantics).
+ALTER TABLE `host_github_tokens` ADD `kind` text DEFAULT 'refresh' NOT NULL;

package/db/migrations/meta/_journal.json

@@ -50,6 +50,13 @@
       "when": 1779900007000,
       "tag": "0006_host_project_env",
       "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "6",
+      "when": 1779900008000,
+      "tag": "0007_host_github_token_kind",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -62,9 +62,13 @@ export type NewHostEventRow = typeof hostEvents.$inferInsert;
 export const githubTokens = sqliteTable("host_github_tokens", {
   userId: text("user_id").primaryKey(),
   installationId: integer("installation_id").notNull(),
+  // ADR-033: holds a long-lived ACCESS token when kind="access", or a refresh
+  // token when kind="refresh" (legacy ADR-027). Encrypted at rest either way.
   refreshTokenCt: blob("refresh_token_ct").notNull(),
   refreshTokenNonce: blob("refresh_token_nonce").notNull(),
   refreshTokenExpiresAt: integer("refresh_token_expires_at"),
+  // "access" (non-expiring, ADR-033) | "refresh" (expiring, ADR-027).
+  kind: text("kind").notNull().default("refresh"),
   updatedAt: integer("updated_at").notNull(),
 });
 

package/lib/agents/claude.ts

@@ -338,6 +338,14 @@ register({
   defaultModel: CLAUDE_DEFAULT_MODEL,
   supportedEfforts: () => [...CLAUDE_EFFORTS],
   defaultEffort: CLAUDE_DEFAULT_EFFORT,
+  // Usable only when a Claude credential is in the env (injected into task
+  // containers at task-up). Gates advertisement (ADR-044 P2).
+  available: () =>
+    Boolean(
+      process.env.CLAUDE_CODE_OAUTH_TOKEN ||
+        process.env.ANTHROPIC_API_KEY ||
+        process.env.ANTHROPIC_AUTH_TOKEN,
+    ),
   create: async ({ agent, containerName, systemPreamble }) =>
     new ClaudeSession({ agent, containerName, systemPreamble }),
 });

package/lib/agents/codex.ts

@@ -28,6 +28,10 @@
  * namespaces inside it anyway.
  */
 
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
 import { newId } from "../ulid";
 import { dockerExecArgs, LineProcess } from "./proc";
 import { register } from "./registry";
@@ -517,6 +521,13 @@ register({
   defaultModel: CODEX_DEFAULT_MODEL,
   supportedEfforts: () => [...CODEX_EFFORTS],
   defaultEffort: CODEX_DEFAULT_EFFORT,
+  // Usable only when the owner's ~/.codex login exists — task-up copies it into
+  // each container from UAI_OWNER_HOME (default $HOME). Gates advertisement
+  // (ADR-044 P2).
+  available: () =>
+    existsSync(
+      join(process.env.UAI_OWNER_HOME?.trim() || homedir(), ".codex", "auth.json"),
+    ),
   create: async ({ agent, containerName, systemPreamble }) =>
     new CodexSession({ agent, containerName, systemPreamble }),
 });

package/lib/agents/registry.ts

@@ -32,6 +32,14 @@ export interface RegisteredAdapter {
   supportedEfforts(): string[];
   /** Preferred effort when the user doesn't pick one. */
   defaultEffort?: string;
+  /**
+   * Whether this kind is usable on THIS host right now — i.e. its credentials
+   * are present (ADR-044 P2). Gates advertisement: an unavailable kind is left
+   * out of `capabilities()` so the cloud's task picker doesn't offer an LLM the
+   * host can't actually run. Omit (or return true) to always advertise; the
+   * session factory stays permissive regardless.
+   */
+  available?: () => boolean;
   /** Builds an AgentSession for a roster entry of this kind. */
   create: AgentSessionFactory["create"];
 }
@@ -76,7 +84,9 @@ export function factoryFor(kind: string): AgentSessionFactory | undefined {
  * Each adapter's `supportedModels()` / `supportedEfforts()` is evaluated here.
  */
 export function capabilities(): AgentKindCapability[] {
-  return list().map((adapter) => {
+  return list()
+    .filter((adapter) => adapter.available?.() ?? true)
+    .map((adapter) => {
     const out: AgentKindCapability = {
       kind: adapter.kind,
       label: adapter.label,

package/lib/command-db.ts

@@ -135,12 +135,12 @@ function insertTask(db: Database.Database, task: CommandTaskRow): void {
       id, owner_user_id, host_id, name, slug, branch, status,
       global_context, reviewer_order, agents, pr_context,
       worktree_path, compose_project, code_server_port, preview_ports,
-      locked_at, started_at, ended_at
+      preview_env, locked_at, started_at, ended_at
     ) VALUES (
       @id, @owner_user_id, @host_id, @name, @slug, @branch, @status,
       @global_context, @reviewer_order, @agents, @pr_context,
       @worktree_path, @compose_project, @code_server_port, @preview_ports,
-      @locked_at, @started_at, @ended_at
+      @preview_env, @locked_at, @started_at, @ended_at
     )`,
   ).run(task);
 }
@@ -166,6 +166,7 @@ interface CommandTaskRow {
   compose_project: string | null;
   code_server_port: number | null;
   preview_ports: string;
+  preview_env: string | null;
   locked_at: number | null;
   started_at: number | null;
   ended_at: number | null;
@@ -193,6 +194,7 @@ function withRuntime(
     compose_project: runtime?.composeProject ?? null,
     code_server_port: runtime?.codeServerPort ?? null,
     preview_ports: runtime?.previewPorts ?? "[]",
+    preview_env: task.previewEnv ? JSON.stringify(task.previewEnv) : null,
     locked_at: runtime?.lockedAt ?? null,
     started_at: runtime?.startedAt ?? null,
     ended_at: runtime?.endedAt ?? null,
@@ -216,6 +218,7 @@ function runtimeTask(taskId: string, runtime: HostTask | null): CommandTaskRow {
     compose_project: runtime?.composeProject ?? null,
     code_server_port: runtime?.codeServerPort ?? null,
     preview_ports: runtime?.previewPorts ?? "[]",
+    preview_env: null,
     locked_at: runtime?.lockedAt ?? null,
     started_at: runtime?.startedAt ?? null,
     ended_at: runtime?.endedAt ?? null,
@@ -262,6 +265,7 @@ CREATE TABLE IF NOT EXISTS uai_tasks (
   compose_project text,
   code_server_port integer,
   preview_ports text NOT NULL DEFAULT '[]',
+  preview_env text,
   pr_url text,
   locked_at integer,
   started_at integer,

package/lib/git-diff.ts

@@ -1,9 +1,10 @@
 /**
  * Parse `git diff` unified output into structured per-file patches.
  *
- * Input is whatever `git diff origin/<base>..HEAD` produces — multi-file,
- * with headers, mode/rename/binary annotations, and `@@` hunks. The
- * output is a list of `DiffFile`s the UI can render per-file with
+ * Input is whatever `git diff <merge-base>` (committed + uncommitted) plus
+ * appended `--no-index` new-file patches for untracked files produce —
+ * multi-file, with headers, mode/rename/binary annotations, and `@@` hunks.
+ * The output is a list of `DiffFile`s the UI can render per-file with
  * collapse/expand and syntax-highlighted hunks.
  *
  * Hand-rolled rather than pulled in as a dep — the unified-diff grammar
@@ -98,34 +99,84 @@ export function runGitDiffInContainer(
   containerName: string,
   cwd: string,
   range: string,
+): Promise<string> {
+  return runDiffCommand(
+    "docker",
+    [...dockerExecPrefix(containerName, cwd), "git", ...GIT_DIFF_ARGS, range],
+    "docker exec git diff",
+    process.env,
+  );
+}
+
+/**
+ * Render a single untracked file as a new-file patch by diffing it against
+ * `/dev/null` with `--no-index`. `git diff <commit>` omits untracked files
+ * entirely, so this is how they reach the "all changes vs base" view.
+ *
+ * `--no-index` exits 1 when the inputs differ (the normal "there is a diff"
+ * case for a new file) and 0 when identical — both are success here; only
+ * code > 1 is a real error.
+ */
+export function runGitDiffUntracked(
+  cwd: string,
+  relPath: string,
+): Promise<string> {
+  return runDiffCommand(
+    "git",
+    ["-C", cwd, ...GIT_DIFF_ARGS, "--no-index", "--", "/dev/null", relPath],
+    "git diff --no-index",
+    { ...process.env, ...NON_INTERACTIVE_GIT_ENV },
+    true,
+  );
+}
+
+/** In-container variant of {@link runGitDiffUntracked}. */
+export function runGitDiffUntrackedInContainer(
+  containerName: string,
+  cwd: string,
+  relPath: string,
 ): Promise<string> {
   return runDiffCommand(
     "docker",
     [
-      "exec",
-      "-e",
-      `GIT_TERMINAL_PROMPT=${NON_INTERACTIVE_GIT_ENV.GIT_TERMINAL_PROMPT}`,
-      "-e",
-      `GCM_INTERACTIVE=${NON_INTERACTIVE_GIT_ENV.GCM_INTERACTIVE}`,
-      "-e",
-      `GIT_SSH_COMMAND=${NON_INTERACTIVE_GIT_ENV.GIT_SSH_COMMAND}`,
-      "-w",
-      cwd,
-      containerName,
+      ...dockerExecPrefix(containerName, cwd),
       "git",
       ...GIT_DIFF_ARGS,
-      range,
+      "--no-index",
+      "--",
+      "/dev/null",
+      relPath,
     ],
-    "docker exec git diff",
+    "docker exec git diff --no-index",
     process.env,
+    true,
   );
 }
 
+/** `docker exec` argv prefix with the non-interactive git env + working dir. */
+function dockerExecPrefix(containerName: string, cwd: string): string[] {
+  return [
+    "exec",
+    "-e",
+    `GIT_TERMINAL_PROMPT=${NON_INTERACTIVE_GIT_ENV.GIT_TERMINAL_PROMPT}`,
+    "-e",
+    `GCM_INTERACTIVE=${NON_INTERACTIVE_GIT_ENV.GCM_INTERACTIVE}`,
+    "-e",
+    `GIT_SSH_COMMAND=${NON_INTERACTIVE_GIT_ENV.GIT_SSH_COMMAND}`,
+    "-w",
+    cwd,
+    containerName,
+  ];
+}
+
 function runDiffCommand(
   command: string,
   args: string[],
   label: string,
   env: NodeJS.ProcessEnv,
+  /** Treat exit code 1 as success — `git diff --no-index` returns 1 when the
+   *  compared inputs differ, which for a new-file patch is the expected case. */
+  allowExitOne = false,
 ): Promise<string> {
   return new Promise((res, rej) => {
     // Force ASCII paths and pull a generous unified context so the UI
@@ -144,7 +195,7 @@ function runDiffCommand(
     });
     child.on("error", rej);
     child.on("close", (code) => {
-      if (code === 0) {
+      if (code === 0 || (allowExitOne && code === 1)) {
         res(stdout);
         return;
       }

package/lib/github-tokens.ts

@@ -26,56 +26,101 @@ type GhConnectSet = Extract<CloudToHost, { kind: "gh.connect.set" }>;
 
 // --- token store ------------------------------------------------------------
 
-/** Encrypt + persist the user's refresh token (gh.connect.set handler). */
+/**
+ * Encrypt + persist the user's token (gh.connect.set handler). ADR-033: a
+ * non-expiring grant carries `accessToken` (stored kind="access", injected
+ * directly); a legacy expiring grant carries `refreshToken` (kind="refresh",
+ * exchanged per task). Exactly one is present.
+ */
 export function onConnectSet(frame: GhConnectSet): { ok: boolean; error?: string } {
   try {
     // Fresh grant — a cached access token from the previous grant may be
     // revoked; drop it so the next mint exchanges against the new token.
     clearAccessCache(frame.userId);
-    const sealed = sealAesGcm(frame.refreshToken);
+    const token = frame.accessToken ?? frame.refreshToken;
+    if (!token) return { ok: false, error: "gh.connect.set carried no token" };
+    const kind = frame.accessToken ? "access" : "refresh";
+    const sealed = sealAesGcm(token);
     const now = Date.now();
+    const fields = {
+      installationId: frame.installationId,
+      refreshTokenCt: sealed.ct,
+      refreshTokenNonce: sealed.nonce,
+      refreshTokenExpiresAt: frame.refreshTokenExpiresAt ?? null,
+      kind,
+      updatedAt: now,
+    };
     getDb()
       .insert(schema.githubTokens)
-      .values({
-        userId: frame.userId,
-        installationId: frame.installationId,
-        refreshTokenCt: sealed.ct,
-        refreshTokenNonce: sealed.nonce,
-        refreshTokenExpiresAt: frame.refreshTokenExpiresAt ?? null,
-        updatedAt: now,
-      })
-      .onConflictDoUpdate({
-        target: schema.githubTokens.userId,
-        set: {
-          installationId: frame.installationId,
-          refreshTokenCt: sealed.ct,
-          refreshTokenNonce: sealed.nonce,
-          refreshTokenExpiresAt: frame.refreshTokenExpiresAt ?? null,
-          updatedAt: now,
-        },
-      })
+      .values({ userId: frame.userId, ...fields })
+      .onConflictDoUpdate({ target: schema.githubTokens.userId, set: fields })
       .run();
+    notifyGithubChange();
     return { ok: true };
   } catch (err) {
     return { ok: false, error: err instanceof Error ? err.message : "store failed" };
   }
 }
 
-/** Delete a user's refresh token + clear their active-task refresh timers. */
-export function onConnectClear(userId: string): void {
-  deleteToken(userId);
-  for (const taskId of activeTaskIdsForUser(userId)) {
-    clearRefresh(taskId);
-    authExpiredHandler?.(taskId, userId, "GitHub disconnected");
+/**
+ * Disconnect GitHub on this host (gh.connect.clear handler). Deletes the token
+ * locally FIRST (so capabilities re-advertise immediately and the UI reflects
+ * removal without waiting on the network), then best-effort revokes it at
+ * GitHub. Whole body is guarded — a fired-and-forgotten failure must never
+ * crash the host (no global unhandledRejection handler).
+ *
+ * ADR-033: only a non-expiring ACCESS token can be revoked by token
+ * (`DELETE /applications/{client_id}/token` matches access tokens only — a
+ * refresh token 404s, which the cloud endpoint would mis-report as success).
+ * Legacy refresh tokens aren't single-token revocable; the short-lived access
+ * tokens they mint expire on their own.
+ */
+export async function onConnectClear(userId: string): Promise<void> {
+  try {
+    const stored = readStoredToken(userId);
+    deleteToken(userId); // fires onGithubChange → re-advertise capabilities
+    for (const taskId of activeTaskIdsForUser(userId)) {
+      clearRefresh(taskId);
+      authExpiredHandler?.(taskId, userId, "GitHub disconnected");
+    }
+    if (stored && stored.kind === "access") {
+      await revokeAtGitHub(stored.token);
+    } else if (stored) {
+      console.warn(
+        `[github] user ${userId}: legacy refresh token cleared locally; cannot single-token revoke at GitHub`,
+      );
+    }
+  } catch (err) {
+    console.warn(
+      `[github] disconnect failed: ${err instanceof Error ? err.message : err}`,
+    );
   }
 }
 
+/** Decrypt the user's stored token + its kind, or null if none. */
+function readStoredToken(
+  userId: string,
+): { token: string; kind: string } | null {
+  const row = getDb()
+    .select()
+    .from(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .get();
+  if (!row) return null;
+  const token = openAesGcm(
+    Buffer.from(row.refreshTokenCt as Uint8Array),
+    Buffer.from(row.refreshTokenNonce as Uint8Array),
+  );
+  return { token, kind: row.kind };
+}
+
 export function deleteToken(userId: string): void {
   clearAccessCache(userId);
   getDb()
     .delete(schema.githubTokens)
     .where(eq(schema.githubTokens.userId, userId))
     .run();
+  notifyGithubChange();
 }
 
 export function hasToken(userId: string): boolean {
@@ -88,6 +133,29 @@ export function hasToken(userId: string): boolean {
   );
 }
 
+/** All cloud user ids with a GitHub token on this host (for capabilities). */
+export function connectedUserIds(): string[] {
+  return getDb()
+    .select({ userId: schema.githubTokens.userId })
+    .from(schema.githubTokens)
+    .all()
+    .map((r) => r.userId);
+}
+
+// Fires whenever the set of stored tokens changes (add/remove), so the host
+// can re-advertise capabilities and the UI reflects per-host gh state promptly.
+let githubChangeHandler: (() => void) | null = null;
+export function onGithubChange(fn: (() => void) | null): void {
+  githubChangeHandler = fn;
+}
+function notifyGithubChange(): void {
+  try {
+    githubChangeHandler?.();
+  } catch {
+    /* never let a listener break token handling */
+  }
+}
+
 function activeTaskIdsForUser(userId: string): string[] {
   return getDb()
     .select({ taskId: schema.hostTasks.taskId })
@@ -104,12 +172,43 @@ function activeTaskIdsForUser(userId: string): string[] {
 
 // --- access-token exchange --------------------------------------------------
 
-function exchangeUrl(): string {
+function cloudHttpBase(): string {
   const cloud = process.env.UAI_CLOUD_URL ?? "ws://127.0.0.1:8789/host";
   const u = new URL(cloud);
   const proto =
     u.protocol === "wss:" ? "https:" : u.protocol === "ws:" ? "http:" : u.protocol;
-  return `${proto}//${u.host}/api/github/oauth/exchange`;
+  return `${proto}//${u.host}`;
+}
+
+function exchangeUrl(): string {
+  return `${cloudHttpBase()}/api/github/oauth/exchange`;
+}
+
+/**
+ * Revoke a token at GitHub via the cloud (which holds the App client secret —
+ * the host can't revoke alone). Same host→cloud HTTP pattern as the exchange;
+ * the token transits the cloud transiently, never stored (ADR-015/ADR-033).
+ * Best-effort — callers proceed to delete locally regardless.
+ */
+async function revokeAtGitHub(token: string): Promise<void> {
+  try {
+    const res = await fetch(`${cloudHttpBase()}/api/github/revoke`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-uai-host-token": process.env.UAI_HOST_TOKEN ?? "",
+      },
+      body: JSON.stringify({ token }),
+      signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+    });
+    if (!res.ok) {
+      console.warn(`[github] token revoke returned HTTP ${res.status}`);
+    }
+  } catch (err) {
+    console.warn(
+      `[github] token revoke failed (deleting locally anyway): ${err instanceof Error ? err.message : err}`,
+    );
+  }
 }
 
 interface ExchangeResult {
@@ -165,7 +264,23 @@ export function clearAllAccessCache(): void {
 
 export function requestAccessToken(
   userId: string,
-): Promise<{ accessToken: string; expiresAt: number } | null> {
+): Promise<{ accessToken: string; expiresAt: number | null } | null> {
+  // ADR-033 non-expiring path: the stored token IS the access token — return it
+  // directly, no exchange/cache/rotation. `expiresAt: null` ⇒ no refresh.
+  const row = getDb()
+    .select({ kind: schema.githubTokens.kind })
+    .from(schema.githubTokens)
+    .where(eq(schema.githubTokens.userId, userId))
+    .get();
+  if (!row) return Promise.resolve(null);
+  if (row.kind === "access") {
+    const stored = readStoredToken(userId);
+    return Promise.resolve(
+      stored ? { accessToken: stored.token, expiresAt: null } : null,
+    );
+  }
+
+  // Legacy expiring path (ADR-027): cache + in-flight dedupe + exchange.
   const cached = accessCache.get(userId);
   if (cached && cached.expiresAt - Date.now() > ACCESS_CACHE_LEAD_MS) {
     return Promise.resolve(cached);
@@ -327,7 +442,8 @@ async function runRefresh(taskId: string, userId: string): Promise<void> {
       return;
     }
     await injectIntoContainer(taskId, tok.accessToken);
-    scheduleRefresh(taskId, userId, tok.expiresAt);
+    // Only re-schedule for an expiring token; non-expiring needs no refresh.
+    if (tok.expiresAt !== null) scheduleRefresh(taskId, userId, tok.expiresAt);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     // A revoked / expired refresh token can't recover — drop it to force a
@@ -423,7 +539,7 @@ export interface SetupTaskDeps {
   hasToken?: (userId: string) => boolean;
   requestAccessToken?: (
     userId: string,
-  ) => Promise<{ accessToken: string; expiresAt: number } | null>;
+  ) => Promise<{ accessToken: string; expiresAt: number | null } | null>;
   inject?: (taskId: string, token: string) => void | Promise<void>;
   schedule?: (taskId: string, userId: string, expiresAt: number) => void;
   deleteToken?: (userId: string) => void;
@@ -460,7 +576,8 @@ export async function setupTaskGithub(
       const tok = await _request(userId);
       if (tok) {
         await _inject(taskId, tok.accessToken);
-        _schedule(taskId, userId, tok.expiresAt);
+        // Non-expiring (ADR-033) tokens (expiresAt null) need no refresh timer.
+        if (tok.expiresAt !== null) _schedule(taskId, userId, tok.expiresAt);
         clearGithubRetry(taskId);
         console.log(`[github] task ${taskId}: injected user access token`);
         return true;

package/lib/orchestrator.ts

@@ -235,14 +235,13 @@ class Orchestrator {
       });
     }
 
-    // Container is ready: deliver each agent's first-turn prompt (ADR-022).
-    // Only agents whose `initialPrompt` was non-empty have an entry.
-    for (const agent of channel.roster) {
-      const firstTurn = channel.firstTurns.get(agent.id);
-      if (firstTurn === undefined) continue;
-      const session = channel.sessions.get(agent.id);
-      if (session) void session.send(firstTurn);
-    }
+    // First-turn delivery is owned by the CLOUD (channel-router.ensureStarted),
+    // which fires each agent's initialPrompt exactly once per task — guarded by
+    // a non-empty message history (its durable "already started" check). The
+    // host must NOT deliver it here: this path re-runs on every session spawn,
+    // so it both duplicated the opening turn AND re-injected it on a host
+    // restart, making agents redo the first turn mid-task. The persona/mission
+    // an agent needs live in the always-on system preamble, so nothing is lost.
     return true;
   }
 
@@ -723,7 +722,11 @@ export function buildSystemPreamble(
   workspacePath: string,
   taskBranch: string,
 ): string {
-  const others = roster.map((a) => `@${a.id} (${a.label})`).join(", ");
+  const channelList = roster
+    .map((a) =>
+      a.id === agent.id ? `@${a.id} (${a.label}, you)` : `@${a.id} (${a.label})`,
+    )
+    .join(", ");
   const projectLines =
     projects.length === 0
       ? ["(none mounted)"]
@@ -739,12 +742,50 @@ export function buildSystemPreamble(
     "it by id at the start of a line — e.g. `@codex please review the",
     "diff`. uai routes that message into that agent's input.",
     "",
-    `Agents in this channel: ${others}.`,
+    `**You are @${agent.id}** — your name in this channel is **${agent.label}**.`,
+    `Introduce and refer to yourself as ${agent.label}, not as a generic`,
+    "assistant or model name.",
+    "",
+    `Agents in this channel: ${channelList}.`,
+    "",
+    "The human you're working with is **@you**. @-mentioning them sends a",
+    "NOTIFICATION, so use it sparingly — only when you actually need them: a",
+    "decision you can't make, a blocker, an approval, or you've finished your",
+    "work and are handing it back for them to act on (e.g. `@you which`",
+    "`approach do you prefer?` or `@you done — PR is up for review`). For",
+    "everything else — status updates, thinking out loud, a direct reply to",
+    "something they just asked, acknowledgments — post in the channel WITHOUT",
+    "@-mentioning @you; they can read the channel and don't need a ping for",
+    "every message. Do NOT reflexively end messages with @you.",
     "",
     "An agent only receives a message when it is explicitly @-mentioned",
-    "(or addressed by the human) — so always @-mention the agent you mean.",
-    "There is NO `peer` command and no shared tmux session; hand-offs are",
-    "just @-mentions in your replies.",
+    "(or addressed by the human) — so always @-mention the agent (or @you)",
+    "you mean. There is NO `peer` command and no shared tmux session;",
+    "hand-offs are just @-mentions in your replies.",
+    "",
+    "Collaborate with your peers — divide up the work, review each other's",
+    "changes, share concrete ideas, and debate approach decisions by",
+    "@-mentioning them. That is how the team gets things done, and you",
+    "should do it freely whenever it moves the work forward. But mentioning",
+    "a peer WAKES it and costs a turn, so make each one count: a message to",
+    "a peer should ADVANCE the work — a real proposal, a question you need",
+    "answered, a hand-off, or a review with specific findings. Do NOT",
+    "@-mention a peer just to greet, thank, agree, acknowledge, or say",
+    "you're ready — content-free replies wake them for nothing and spiral",
+    "into endless back-and-forth. If you have nothing substantive to add,",
+    "don't @-mention back. And when there's no active task yet (intros, or",
+    "you're waiting on the human), answer briefly and then wait — you don't",
+    "need to @-mention anyone (including @you); they can see the channel.",
+    "",
+    "When a message already @-mentions several participants at once (the",
+    "human asking the whole group, or a peer addressing multiple agents),",
+    "it's a group broadcast — this is a GROUP CHAT and everyone named has",
+    "ALREADY been notified and will answer for themselves. Just answer for",
+    "YOUR part. Do NOT re-@-mention the others to prompt them, hand the",
+    "question to them, or wait on them — no `I'll let @x speak`, `@x your",
+    "turn`, or `still waiting on @x`. Re-mentioning someone who already got",
+    "the message only wakes them again and spirals into duplicate replies.",
+    "Say your piece and stop.",
     "",
     "Because your input is only what you're addressed, you may be missing",
     "context from messages between the human and the other agents. The full",
@@ -757,9 +798,11 @@ export function buildSystemPreamble(
     "and committed your changes, or completed a review, end your reply by",
     "@-mentioning the agent who should act next and telling them what you",
     "did and what you need (e.g. `@codex changes committed on <branch> —",
-    "please review`, or `@claude review done, N issues to fix`). Never",
-    "stop silently — if genuinely no agent needs to act, say so to the",
-    "human.",
+    "please review`, or `@claude review done, N issues to fix`). Don't",
+    "abandon unfinished work silently — but once your part is done and no",
+    "peer needs to act, it's fine to stop; only @-mention @you if you need",
+    "their input or are handing back finished work for them to act on. Don't",
+    "prolong an agent-to-agent exchange just to fill silence.",
     "",
     "## Workspace layout",
     "",