@armadra/agent 0.6.2 → 0.6.4

package/dist/cli/compose-agents.d.ts

@@ -5,7 +5,8 @@
  * `agentDirs` → config `agents.dirs` → 用户级 → 项目级（需信任）），建类型目录并绑到 task 工具
  * （描述里的类型清单）；工厂给每个根会话装一个扩展：建任务注册表（subagent-registry.ts，并发 /
  * 排队上限与模型别名取自 config），`getStats().tasks` 汇总，会话 dispose 时停止后台任务。
- * task 子会话（depth ≥ 1）与没有 task 工具的会话不装。
+ * task 子会话（depth ≥ 1）与没有 task 工具的会话不装。[W7-B1] `subagents.background`（auto：交互 / RPC /
+ * ACP 后台、`-p` 前台）解析成本进程的缺省，同时决定 task 描述的版本；`autoBackgroundAfterMs` 透传。
  *
  * [W5-EG] 外部 runner（claude / codex / acp:* / 宿主注入）经 agents/external.ts 接入 `runners`：每个主
  * 会话一个 ExternalAgents（审批接 requestApproval，只交给人）；PATH 上的 claude / codex 登记进类型

package/dist/cli/compose-agents.js

@@ -5,7 +5,8 @@
  * `agentDirs` → config `agents.dirs` → 用户级 → 项目级（需信任）），建类型目录并绑到 task 工具
  * （描述里的类型清单）；工厂给每个根会话装一个扩展：建任务注册表（subagent-registry.ts，并发 /
  * 排队上限与模型别名取自 config），`getStats().tasks` 汇总，会话 dispose 时停止后台任务。
- * task 子会话（depth ≥ 1）与没有 task 工具的会话不装。
+ * task 子会话（depth ≥ 1）与没有 task 工具的会话不装。[W7-B1] `subagents.background`（auto：交互 / RPC /
+ * ACP 后台、`-p` 前台）解析成本进程的缺省，同时决定 task 描述的版本；`autoBackgroundAfterMs` 透传。
  *
  * [W5-EG] 外部 runner（claude / codex / acp:* / 宿主注入）经 agents/external.ts 接入 `runners`：每个主
  * 会话一个 ExternalAgents（审批接 requestApproval，只交给人）；PATH 上的 claude / codex 登记进类型
@@ -17,7 +18,8 @@ import { AgentCatalog } from "../agents/catalog.js";
 import { agentSources, discoverAgents } from "../agents/discover.js";
 import { NO_AGENT_PROBE_ENV, SessionExternalAgents, registerExternalAgents, } from "../agents/external.js";
 import { hostRunnersOf } from "../host/api-impl.js";
-import { bindTaskAgents } from "../tools/task.js";
+import { bindTaskAgents, bindTaskBackground } from "../tools/task.js";
+import { resolveTaskBackground } from "../agent/subagent-background.js";
 import { msg } from "../i18n/index.js";
 /** 同一装配材料只提示一次（`/new` 等会重新装配会话）。 */
 const warned = new WeakSet();
@@ -54,6 +56,12 @@ export function subagentEnvironment(deps, catalog) {
     const pending = config.subagents?.maxPending;
     if (pending !== undefined)
         env.maxPending = pending;
+    // [W7-B1] 缺省后台与自动转后台（配置键 W7-B2 登记于 config/types-w5.ts）
+    const sub = config.subagents;
+    env.background = resolveTaskBackground(sub?.background, deps.assembly.unattended === true);
+    const after = sub?.autoBackgroundAfterMs;
+    if (typeof after === "number" && after > 0)
+        env.autoBackgroundAfterMs = after;
     return env;
 }
 /** 外部 Agent 的装配材料（宿主、信任、探测开关取自装配材料与环境）。 */
@@ -108,5 +116,6 @@ export function createSubagentsFactory(deps) {
     registerExternalAgents(catalog, wiring);
     bindTaskAgents(task, catalog);
     const env = subagentEnvironment(deps, catalog);
+    bindTaskBackground(task, env.background === true);
     return ({ core }) => (core.depth > 0 ? undefined : createSubagentExtension(core, env, wiring));
 }

package/dist/cli/subcommands/models-discover.d.ts

@@ -21,6 +21,7 @@
  * `GET /models?client_version=<codexClientVersion>`，另带上下文窗口 / 输入模态 / 推理强度），取 slug 与显示名；
  * `--probe` 不适用（订阅后端只有一种协议）。结果另写进发现缓存 `<dataDir>/models/discovered/chatgpt.json`
  * （discovered-cache.ts，0 个也写），`/model` 选择器由此列出；codex 返回 0 个时提示 codexClientVersion 可能过旧。
+ * 后端给了上下文窗口就显示它（标「后端」），注册表同样以它为准；没给的列出来，说明改用 models.dev。
  */
 import type { Api, Model, ProviderData, ProviderRegistryApi } from "../../ai/types.js";
 import type { ModelsAction } from "./models.js";

package/dist/cli/subcommands/models-discover.js

@@ -21,6 +21,7 @@
  * `GET /models?client_version=<codexClientVersion>`，另带上下文窗口 / 输入模态 / 推理强度），取 slug 与显示名；
  * `--probe` 不适用（订阅后端只有一种协议）。结果另写进发现缓存 `<dataDir>/models/discovered/chatgpt.json`
  * （discovered-cache.ts，0 个也写），`/model` 选择器由此列出；codex 返回 0 个时提示 codexClientVersion 可能过旧。
+ * 后端给了上下文窗口就显示它（标「后端」），注册表同样以它为准；没给的列出来，说明改用 models.dev。
  */
 import { authHeaders, mergeHeaders } from "../../ai/http.js";
 import { listChatGptModels } from "../../auth/chatgpt/backend-client.js";
@@ -226,13 +227,22 @@ async function run(ctx) {
             noTools.add(model.id);
         if (match === undefined)
             unmatched.add(model.id);
+        // 后端给的上下文窗口优先于 models.dev（订阅后端的生效窗口可能远小于 API 版）
+        const backendCtx = model.contextWindow !== undefined
+            ? `  ctx ${compactTokens(model.contextWindow)}${m.fromBackend}`
+            : undefined;
         const meta = fields === undefined
-            ? m.unmatched
-            : `  ctx ${compactTokens(fields.contextWindow)} · out ${compactTokens(fields.maxTokens)}` +
+            ? `${backendCtx ?? ""}${m.unmatched}`
+            : `${backendCtx ?? `  ctx ${compactTokens(fields.contextWindow)}`} · out ${compactTokens(fields.maxTokens)}` +
                 `${fields.input?.includes("image") ? m.image : ""}${fields.reasoning ? m.reasoning : ""}` +
                 `${fields.toolCall === false ? m.noTools : ""} · ${matchLabel(match)}`;
         io.stdout(`  ${model.id}${known !== undefined ? m.configured(known.api) : ""}${meta}\n`);
     }
+    if (provider.id === CHATGPT_PROVIDER_ID) {
+        const missing = found.filter((x) => x.contextWindow === undefined).map((x) => x.id);
+        if (missing.length > 0)
+            io.stdout(m.noBackendWindow(missing.join(", ")));
+    }
     const write = ctx.flags.has("write");
     if (!ctx.flags.has("probe") || provider.id === CHATGPT_PROVIDER_ID) {
         if (write)

package/dist/config/json-schema.js

@@ -13,7 +13,7 @@ import { defaultFor, isDynamicDefault, keyDoc } from "./key-docs.js";
 import { HOOK_TIMEOUT_MAX_MS, THINKING_LEVELS } from "./schema.js";
 import { CACHE_RETENTIONS, CHANNEL_NAME_PATTERN, CHECKPOINT_MODES, SANDBOX_ENABLED_MODES, SANDBOX_NETWORK_MODES, CODEMODE_MODES, IMAGE_RESIZE_MODES, PLAN_BASH_MODES_STRICT_FIRST, PLAN_UNATTENDED_MODES, STATUS_LINE_MODES, TOOLS_PRESET_INPUTS, LANGUAGE_SETTINGS, AGENT_BAR_MODES, CHATGPT_FLAVORS, MEMORY_SCOPES, MEMORY_SUBAGENT_MODES, } from "./types.js";
 import { AGENT_ID_PATTERN } from "./schema-w5.js";
-import { AGENTS_RESERVED_KEYS } from "./types-w5.js";
+import { AGENTS_RESERVED_KEYS, SUBAGENT_BACKGROUND_MODES } from "./types-w5.js";
 export const CONFIG_SCHEMA_FILE = "config.schema.json";
 export const CONFIG_SCHEMA_ID = "https://github.com/Owlbay/armadra-agent/config.schema.json";
 const KNOWN_APIS = [
@@ -150,7 +150,13 @@ function w5Sections() {
                 pattern: `^(${AGENTS_RESERVED_KEYS.join("|")}|${AGENT_ID_PATTERN.source.slice(1, -1)})$`,
             },
         }),
-        subagents: object({ maxConcurrent: num(1, 64), maxPending: num(0, 1024), defaultModel: str() }),
+        subagents: object({
+            maxConcurrent: num(1, 64),
+            maxPending: num(0, 1024),
+            defaultModel: str(),
+            background: oneOf(SUBAGENT_BACKGROUND_MODES),
+            autoBackgroundAfterMs: num(0),
+        }),
         models: object({ aliases: object({ fast: str(), strong: str() }), enabled: strings }),
         fallbackModel: str(),
         limits: object({ maxTurns: num(1), maxCostUsd: num(0) }),
@@ -271,8 +277,10 @@ function buildBaseSchema() {
                 quietStartup: oneOf(["normal", "header", "silent"]),
                 ascii: bool(),
                 compact: bool(),
+                logo: oneOf(["auto", "off"]),
                 animation: bool(),
                 restoreOnCancel: bool(),
+                enterWhileRunning: oneOf(["queue", "interrupt"]),
                 statusLine: oneOf(STATUS_LINE_MODES),
                 language: oneOf(LANGUAGE_SETTINGS),
                 replyLanguage: str(),

package/dist/config/key-docs.js

@@ -23,7 +23,14 @@ const IMPLICIT_DEFAULTS = {
     codemode: { inlineBudget: DEFAULT_INLINE_BUDGET, requireStrict: false },
     cache: { ...DEFAULT_CACHE_CONFIG },
     request: { idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS },
-    ui: { compact: false, animation: true, restoreOnCancel: true, language: "auto" },
+    ui: {
+        compact: false,
+        logo: "auto",
+        animation: true,
+        restoreOnCancel: true,
+        enterWhileRunning: "queue",
+        language: "auto",
+    },
     // [W6-C0] 第六波键的缺省（行为由各批次实现）
     memory: {
         enabled: false,
@@ -48,7 +55,7 @@ const IMPLICIT_DEFAULTS = {
     images: { resize: "auto" },
     plan: { bash: "readonly", unattended: "stop" },
     agents: { maxConcurrent: 3, dirs: [] },
-    subagents: { maxConcurrent: 4, maxPending: 16 },
+    subagents: { maxConcurrent: 4, maxPending: 16, background: "auto", autoBackgroundAfterMs: 0 },
     reminders: { todo: true, fileChanges: true, contextPressure: true, budget: true },
     todo: { reminder: 10 },
 };

package/dist/config/merge.d.ts

@@ -9,7 +9,7 @@
  *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`、
  *   `checkpoints.mode: "off"`、`checkpoints.maxFileBytes`（只能调小）、（W5-C0）`plan.bash`（只能更严）、
  *   `reminders`；`compaction.prune / pruneExclude` 与第五波其余段只认用户级；（W6-C0）`ui.language` /
- *   `ui.agentBar` 随 `ui` 段、`memory.enabled: false`；`ui.replyLanguage`、`memory` 其余键、`auth` 只认用户级；
+ *   `ui.agentBar` 随 `ui` 段、`memory.enabled: false`；（W7-B2）`subagents.background / autoBackgroundAfterMs`；`ui.replyLanguage`、`memory` 其余键、`auth` 只认用户级；
  *   其它字段与放宽项（含 `permission.builtinDeny / autoModel / autoSafeCommands`）被忽略并记 warning。
  * - 同时产出带来源的权限规则清单（`ruleSpecs`），交给权限管线（B3 的 rules.ts 解析）。
  */

package/dist/config/merge.js

@@ -9,7 +9,7 @@
  *   `compaction`、`tools.disabled`、`tools.preset`（只能更严）、`codemode.mode: "off"`、`ui`、
  *   `checkpoints.mode: "off"`、`checkpoints.maxFileBytes`（只能调小）、（W5-C0）`plan.bash`（只能更严）、
  *   `reminders`；`compaction.prune / pruneExclude` 与第五波其余段只认用户级；（W6-C0）`ui.language` /
- *   `ui.agentBar` 随 `ui` 段、`memory.enabled: false`；`ui.replyLanguage`、`memory` 其余键、`auth` 只认用户级；
+ *   `ui.agentBar` 随 `ui` 段、`memory.enabled: false`；（W7-B2）`subagents.background / autoBackgroundAfterMs`；`ui.replyLanguage`、`memory` 其余键、`auth` 只认用户级；
  *   其它字段与放宽项（含 `permission.builtinDeny / autoModel / autoSafeCommands`）被忽略并记 warning。
  * - 同时产出带来源的权限规则清单（`ruleSpecs`），交给权限管线（B3 的 rules.ts 解析）。
  */
@@ -35,8 +35,9 @@ export const DEFAULT_CONFIG = Object.freeze({
 });
 /** 嵌入宿主（有 profile）时的缺省覆盖（§12.10）。 */
 export const PROFILE_DEFAULTS = Object.freeze({
-    // [W5-A] 嵌入宿主以「最后一行 = 状态栏」锚定，底部信息行缺省单行；[W6-C0] 宿主自己展示节点，Agent 栏缺省关
-    ui: { quietStartup: "header", statusLine: "compact", agentBar: "off" },
+    // [W5-A] 嵌入宿主以「最后一行 = 状态栏」锚定，底部信息行缺省单行；[W7-A] Agent 栏不再缺省关，
+    // 宿主要关就在自己的 profile 写 `ui.agentBar: "off"`
+    ui: { quietStartup: "header", statusLine: "compact" },
 });
 /** 层名 → 规则来源（RuleSource）。 */
 const RULE_SOURCE = {
@@ -120,6 +121,22 @@ export function restrictProjectConfig(project, currentMode, label = ".ama/config
                 if (project.reminders !== undefined)
                     accepted.reminders = structuredClone(project.reminders);
                 break;
+            case "subagents": {
+                // [W7-B2] 前台 / 后台只影响呈现与等待，不放宽权限：项目级可设；并发、模型仍只认用户级
+                const subagents = project.subagents ?? {};
+                const result = {};
+                for (const sub of Object.keys(subagents)) {
+                    if (sub !== "background" && sub !== "autoBackgroundAfterMs")
+                        warnings.push(msg().config.merge.projectOnlyKeys(label, "subagents.background / subagents.autoBackgroundAfterMs", `subagents.${sub}`));
+                }
+                if (subagents.background !== undefined)
+                    result.background = subagents.background;
+                if (subagents.autoBackgroundAfterMs !== undefined)
+                    result.autoBackgroundAfterMs = subagents.autoBackgroundAfterMs;
+                if (Object.keys(result).length > 0)
+                    accepted.subagents = result;
+                break;
+            }
             case "plan": {
                 const plan = restrictPlan(project.plan ?? {}, currentPlanBash, label, warnings);
                 if (plan !== undefined)

package/dist/config/schema-w5.js

@@ -7,7 +7,7 @@
 import { PERMISSION_MODES_STRICT_FIRST } from "../permissions/types.js";
 import { msg } from "../i18n/index.js";
 import { Checker, THINKING_LEVELS, checkSection, join } from "./checker.js";
-import { AGENTS_RESERVED_KEYS, IMAGE_RESIZE_MODES, MODELS_ENABLED_REF, PLAN_BASH_MODES_STRICT_FIRST, PLAN_UNATTENDED_MODES, STATUS_LINE_MODES, } from "./types-w5.js";
+import { AGENTS_RESERVED_KEYS, IMAGE_RESIZE_MODES, MODELS_ENABLED_REF, PLAN_BASH_MODES_STRICT_FIRST, PLAN_UNATTENDED_MODES, STATUS_LINE_MODES, SUBAGENT_BACKGROUND_MODES, } from "./types-w5.js";
 /** 第五波新增的顶层键（schema.ts 的 CONFIG_KEYS 并入）。 */
 export const W5_CONFIG_KEYS = [
     "images",
@@ -83,10 +83,12 @@ export function validateConfigW5(c, config) {
         c.oneOf(s, "thinkingLevel", p, THINKING_LEVELS);
     });
     checkAgents(c, config);
-    checkSection(c, config, "subagents", ["maxConcurrent", "maxPending", "defaultModel"], (s, p) => {
+    checkSection(c, config, "subagents", ["maxConcurrent", "maxPending", "defaultModel", "background", "autoBackgroundAfterMs"], (s, p) => {
         c.number(s, "maxConcurrent", p, 1, 64);
         c.number(s, "maxPending", p, 0, 1024);
         c.string(s, "defaultModel", p);
+        c.oneOf(s, "background", p, SUBAGENT_BACKGROUND_MODES);
+        c.number(s, "autoBackgroundAfterMs", p, 0);
     });
     checkSection(c, config, "models", ["aliases", "enabled"], (s, p) => {
         c.stringArray(s, "enabled", p);

package/dist/config/schema.js

@@ -257,8 +257,10 @@ export function validateConfig(value) {
         "quietStartup",
         "ascii",
         "compact",
+        "logo",
         "animation",
         "restoreOnCancel",
+        "enterWhileRunning",
         ...W5_UI_KEYS,
         ...W6_UI_KEYS,
     ], (s, p) => {
@@ -269,8 +271,10 @@ export function validateConfig(value) {
         c.oneOf(s, "quietStartup", p, ["normal", "header", "silent"]);
         c.boolean(s, "ascii", p);
         c.boolean(s, "compact", p);
+        c.oneOf(s, "logo", p, ["auto", "off"]);
         c.boolean(s, "animation", p);
         c.boolean(s, "restoreOnCancel", p);
+        c.oneOf(s, "enterWhileRunning", p, ["queue", "interrupt"]);
         checkUiW5(c, s, p);
         checkUiW6(c, s, p);
     });

package/dist/config/settings-registry.js

@@ -31,8 +31,10 @@ const ROWS = [
     row("ui.showThinking", "ui", "now", "any"),
     row("ui.compact", "ui", "now", "any"),
     row("ui.animation", "ui", "now", "any"),
+    row("ui.logo", "ui", "restart", "any"),
     row("ui.statusLine", "ui", "now", "any"),
     row("ui.restoreOnCancel", "ui", "nextSession", "any"),
+    row("ui.enterWhileRunning", "ui", "now", "any"),
     row("ui.quietStartup", "ui", "restart", "any"),
     row("ui.ascii", "ui", "restart", "any", { envOverride: "AMA_ASCII" }),
     row("ui.language", "ui", "restart", "any", { envOverride: "AMA_LANG" }),
@@ -92,6 +94,9 @@ const ROWS = [
     row("agents.sessionBudgetUsd", "agents", "nextSession", "deny", { kind: "optionalNumber" }),
     row("subagents.maxConcurrent", "agents", "nextSession", "deny"),
     row("subagents.maxPending", "agents", "nextSession", "deny"),
+    // [W7-B2] 改 task 工具描述（缺省后台 / 前台两种文案），故 prefix
+    row("subagents.background", "agents", "restart", "any", { prefix: true }),
+    row("subagents.autoBackgroundAfterMs", "agents", "restart", "any"),
     // [W6-M]
     row("memory.enabled", "memory", "nextSession", "tighten", { envOverride: "AMA_MEMORY" }),
     row("memory.subagents", "memory", "nextSession", "deny"),

package/dist/config/types-w5.d.ts

@@ -59,6 +59,9 @@ export interface AgentsConfig {
 }
 /** 取 `agents.<id>`（保留键返回 undefined）。 */
 export declare function agentEntry(agents: AgentsConfig | undefined, agentId: string): AgentEntryConfig | undefined;
+/** [W7-B2] 子 Agent 缺省前台还是后台（docs/agents-concurrency-plan.md §2.6）。 */
+export declare const SUBAGENT_BACKGROUND_MODES: readonly ["auto", "always", "never"];
+export type SubagentBackgroundMode = (typeof SUBAGENT_BACKGROUND_MODES)[number];
 /** [W5-G] ama 自己的子会话。 */
 export interface SubagentsConfig {
     /** 同时运行的子会话，缺省 4。 */
@@ -67,6 +70,13 @@ export interface SubagentsConfig {
     maxPending?: number;
     /** 子会话缺省模型；不设继承父会话。 */
     defaultModel?: string;
+    /**
+     * [W7-B2] task 缺省后台：auto（缺省）= 交互 / RPC / ACP 下后台、`-p` 下前台；always / never 固定。
+     * 优先级：调用参数 > 类型定义 > 本键。用户 / 项目 / 宿主级都认。
+     */
+    background?: SubagentBackgroundMode;
+    /** [W7-B2] 前台任务运行超过该毫秒数自动转后台；缺省 0 关闭。用户 / 项目级都认。 */
+    autoBackgroundAfterMs?: number;
 }
 /** `models.enabled` 的一项：`provider/model[@channel]` 或 `provider/*`。 */
 export declare const MODELS_ENABLED_REF: RegExp;

package/dist/config/types-w5.js

@@ -18,5 +18,7 @@ export function agentEntry(agents, agentId) {
     const entry = agents[agentId];
     return typeof entry === "object" && !Array.isArray(entry) ? entry : undefined;
 }
+/** [W7-B2] 子 Agent 缺省前台还是后台（docs/agents-concurrency-plan.md §2.6）。 */
+export const SUBAGENT_BACKGROUND_MODES = ["auto", "always", "never"];
 /** `models.enabled` 的一项：`provider/model[@channel]` 或 `provider/*`。 */
 export const MODELS_ENABLED_REF = /^[^/\s]+\/\S+$/;

package/dist/config/types.d.ts

@@ -143,12 +143,16 @@ export interface UiConfig extends UiConfigW6 {
     quietStartup?: "normal" | "header" | "silent";
     /** ASCII 字形（`AMA_ASCII=1` 等价）；缺省按区域设置 / TERM 自动检测。 */
     ascii?: boolean;
-    /** 消息区块间不空行、启动头无框，缺省 false。 */
+    /** 消息区块间不空行、启动头不画字符画，缺省 false。 */
     compact?: boolean;
+    /** 启动头的「AMA」字符画：auto（缺省，宽度够时画）/ off（只画信息列）。 */
+    logo?: "auto" | "off";
     /** false：运行中 spinner 固定为 `·`，缺省 true。 */
     animation?: boolean;
     /** 运行中 Esc 中断、本回合还没有任何输出时撤回该回合并回填原消息，缺省 true。 */
     restoreOnCancel?: boolean;
+    /** 运行中按 Enter：queue（缺省）排队插话，interrupt 打断并立即发送（与 `app.message.interrupt` 互换）。 */
+    enterWhileRunning?: "queue" | "interrupt";
     /** [W5-C0] 底部信息行（W5-A）：缺省独立终端 full、嵌入宿主（有 profile）compact。 */
     statusLine?: StatusLineMode;
 }

package/dist/drivers/runner.js

@@ -135,6 +135,16 @@ export class ProcessRunner {
         return this.deps;
     }
 }
+/**
+ * 能中断单个回合、进程留着接着用的驱动（ACP `session/cancel`、Claude stream-json interrupt、Codex
+ * `turn/interrupt`）；oneshot 每回合一个进程（中断 = 杀进程），宿主驱动不归 ama 管——这两种「打断并发送」退回排队。
+ */
+const TURN_INTERRUPT = new Set([
+    "acp",
+    "acp-adapter",
+    "claude-stream",
+    "codex-app-server",
+]);
 class ProcessHandle {
     runner;
     chosen;
@@ -209,8 +219,25 @@ class ProcessHandle {
         }
         this.chain = this.chain.then(() => this.runTurn(text));
     }
-    wait() {
-        return this.chain;
+    /** 跟到链尾：回合进行中被 `interrupt` 接上的下一回合也算在这次运行里。 */
+    async wait() {
+        for (;;) {
+            const chain = this.chain;
+            const result = await chain;
+            if (chain === this.chain)
+                return result;
+        }
+    }
+    /** 子 Agent 视图的「打断并发送」：中断当前回合，紧接着以 `text` 开下一回合。 */
+    async interrupt(text) {
+        const session = this.session;
+        if (this.stopped || !this.busy || session === undefined)
+            return false;
+        if (!TURN_INTERRUPT.has(this.chosen.driver.kind))
+            return false;
+        this.chain = this.chain.then(() => this.runTurn(text));
+        await session.cancel();
+        return true;
     }
     async stop() {
         if (this.stopped)

package/dist/git/info.d.ts

@@ -7,6 +7,9 @@
  *   `GIT_OPTIONAL_LOCKS=0`；两次之间 ≥ `minIntervalMs`（缺省 10 s），超过 `timeoutMs`（缺省 2 s）或
  *   非零退出 / 起不来就省略增删项，并在本实例（本会话）停用 numstat，HEAD 仍照常显示。
  *   `AMA_STATUS_GIT=0` 直接关闭 numstat（排错用）。
+ * - [W6] 领先 / 落后上游：当前分支在 git 配置里有 `branch.<名>.merge`（零依赖读 config，不起进程判断）时，
+ *   numstat 之后同一节流周期再跑 `git rev-list --left-right --count @{upstream}...HEAD`（同样的超时与环境）；
+ *   没有上游、detached、非零退出就省略；超时则本会话不再统计领先 / 落后。`AMA_STATUS_GIT=0` 同样关闭。
  * - 非 git 目录 `current()` 为 undefined（状态行整段省略）。
  * - `refresh()` 在回合边界调用（agent_settled、写类工具结束、回滚、/tree），只发起读取、不阻塞；
  *   结果有变化时通知 `onChange` 的监听者。
@@ -19,6 +22,9 @@ export interface GitInfo {
     /** 工作区（含暂存）相对 HEAD；拿不到为 undefined。 */
     insertions?: number;
     deletions?: number;
+    /** [W6] 领先 / 落后上游的提交数；没有上游为 undefined。 */
+    ahead?: number;
+    behind?: number;
 }
 /** numstat 子进程的最小接口（测试注入）。 */
 export interface NumstatProcess {
@@ -45,6 +51,13 @@ export declare function parseNumstat(text: string): {
     insertions: number;
     deletions: number;
 };
+/** `git rev-list --left-right --count @{upstream}...HEAD` 的输出：左（上游独有）= 落后，右 = 领先。 */
+export declare function parseLeftRight(text: string): {
+    ahead: number;
+    behind: number;
+} | undefined;
+/** 分支在 git 配置里有没有上游（`[branch "<名>"]` 段里的 `merge`）；worktree 读主仓库的 config。 */
+export declare function hasUpstream(cwd: string, branch: string): Promise<boolean>;
 export declare class GitInfoWatcher {
     private readonly cwd;
     private info;
@@ -61,6 +74,8 @@ export declare class GitInfoWatcher {
     private headAgain;
     private disposed;
     private diff;
+    private upstream;
+    private upstreamDisabled;
     constructor(cwd: string, deps?: GitInfoDeps);
     current(): GitInfo | undefined;
     /** numstat 已因超时 / 失败 / 环境变量停用。 */
@@ -71,5 +86,9 @@ export declare class GitInfoWatcher {
     dispose(): void;
     private update;
     private maybeNumstat;
+    /** 领先 / 落后上游：只在配置里有上游时起进程；超时本会话停用，非零退出只省略这一次。 */
+    private leftRight;
     private numstat;
+    /** 后台起一次 git；起不来为 undefined，超时杀掉并返回 `"timeout"`。 */
+    private run;
 }

package/dist/git/info.js

@@ -7,13 +7,16 @@
  *   `GIT_OPTIONAL_LOCKS=0`；两次之间 ≥ `minIntervalMs`（缺省 10 s），超过 `timeoutMs`（缺省 2 s）或
  *   非零退出 / 起不来就省略增删项，并在本实例（本会话）停用 numstat，HEAD 仍照常显示。
  *   `AMA_STATUS_GIT=0` 直接关闭 numstat（排错用）。
+ * - [W6] 领先 / 落后上游：当前分支在 git 配置里有 `branch.<名>.merge`（零依赖读 config，不起进程判断）时，
+ *   numstat 之后同一节流周期再跑 `git rev-list --left-right --count @{upstream}...HEAD`（同样的超时与环境）；
+ *   没有上游、detached、非零退出就省略；超时则本会话不再统计领先 / 落后。`AMA_STATUS_GIT=0` 同样关闭。
  * - 非 git 目录 `current()` 为 undefined（状态行整段省略）。
  * - `refresh()` 在回合边界调用（agent_settled、写类工具结束、回滚、/tree），只发起读取、不阻塞；
  *   结果有变化时通知 `onChange` 的监听者。
  */
 import { spawn as nodeSpawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { findGitDir, readGitHead } from "../checkpoints/git-head.js";
 export const GIT_NUMSTAT_INTERVAL_MS = 10_000;
 export const GIT_NUMSTAT_TIMEOUT_MS = 2_000;
@@ -30,6 +33,32 @@ export function parseNumstat(text) {
     }
     return { insertions, deletions };
 }
+/** `git rev-list --left-right --count @{upstream}...HEAD` 的输出：左（上游独有）= 落后，右 = 领先。 */
+export function parseLeftRight(text) {
+    const match = /^\s*(\d+)\s+(\d+)\s*$/.exec(text);
+    return match === null ? undefined : { behind: Number(match[1]), ahead: Number(match[2]) };
+}
+/** 分支在 git 配置里有没有上游（`[branch "<名>"]` 段里的 `merge`）；worktree 读主仓库的 config。 */
+export async function hasUpstream(cwd, branch) {
+    const gitDir = await findGitDir(cwd);
+    if (gitDir === undefined)
+        return false;
+    const common = (await readFile(join(gitDir, "commondir"), "utf8").catch(() => undefined))?.trim();
+    const dir = common === undefined ? gitDir : isAbsolute(common) ? common : resolve(gitDir, common);
+    const text = await readFile(join(dir, "config"), "utf8").catch(() => "");
+    let inBranch = false;
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        const section = /^\[\s*([^\]\s"]+)(?:\s+"((?:[^"\\]|\\.)*)")?\s*\]/.exec(line);
+        if (section !== null) {
+            inBranch = section[1]?.toLowerCase() === "branch" && section[2] === branch;
+            continue;
+        }
+        if (inBranch && /^merge\s*=\s*\S/i.test(line))
+            return true;
+    }
+    return false;
+}
 async function readHead(cwd) {
     const head = await readGitHead(cwd);
     if (head !== undefined) {
@@ -50,6 +79,8 @@ const sameInfo = (a, b) => a?.branch === b?.branch &&
     a?.shortHead === b?.shortHead &&
     a?.insertions === b?.insertions &&
     a?.deletions === b?.deletions &&
+    a?.ahead === b?.ahead &&
+    a?.behind === b?.behind &&
     (a === undefined) === (b === undefined);
 export class GitInfoWatcher {
     cwd;
@@ -67,6 +98,8 @@ export class GitInfoWatcher {
     headAgain = false;
     disposed = false;
     diff;
+    upstream;
+    upstreamDisabled;
     constructor(cwd, deps = {}) {
         this.cwd = cwd;
         this.spawn = deps.spawn ?? ((command, args, options) => nodeSpawn(command, args, options));
@@ -75,6 +108,7 @@ export class GitInfoWatcher {
         this.timeoutMs = deps.timeoutMs ?? GIT_NUMSTAT_TIMEOUT_MS;
         this.env = deps.env ?? process.env;
         this.numstatDisabled = this.env["AMA_STATUS_GIT"] === "0";
+        this.upstreamDisabled = this.numstatDisabled;
     }
     current() {
         return this.info;
@@ -118,6 +152,7 @@ export class GitInfoWatcher {
             : {
                 ...head,
                 ...(this.diff !== undefined && head.shortHead !== undefined ? this.diff : {}),
+                ...(this.upstream !== undefined && head.branch !== undefined ? this.upstream : {}),
             };
         if (sameInfo(this.info, next))
             return;
@@ -135,8 +170,7 @@ export class GitInfoWatcher {
             return Promise.resolve();
         this.lastNumstatAt = at;
         this.numstatRunning = true;
-        return this.numstat().then((diff) => {
-            this.numstatRunning = false;
+        return this.numstat().then(async (diff) => {
             if (this.disposed)
                 return;
             if (diff === undefined) {
@@ -145,14 +179,36 @@ export class GitInfoWatcher {
             }
             else
                 this.diff = diff;
+            await this.leftRight();
+            this.numstatRunning = false;
+            if (this.disposed)
+                return;
             const info = this.info;
             if (info === undefined)
                 return;
-            const { insertions: _i, deletions: _d, ...head } = info;
+            const { insertions: _i, deletions: _d, ahead: _a, behind: _b, ...head } = info;
             this.update(head);
         });
     }
-    numstat() {
+    /** 领先 / 落后上游：只在配置里有上游时起进程；超时本会话停用，非零退出只省略这一次。 */
+    async leftRight() {
+        const branch = this.info?.branch;
+        if (this.upstreamDisabled || branch === undefined || !(await hasUpstream(this.cwd, branch))) {
+            this.upstream = undefined;
+            return;
+        }
+        const result = await this.run(["rev-list", "--left-right", "--count", "@{upstream}...HEAD"]);
+        if (result === "timeout")
+            this.upstreamDisabled = true;
+        this.upstream =
+            typeof result === "object" && result.code === 0 ? parseLeftRight(result.out) : undefined;
+    }
+    async numstat() {
+        const result = await this.run(["diff", "--numstat", "HEAD"]);
+        return typeof result === "object" && result.code === 0 ? parseNumstat(result.out) : undefined;
+    }
+    /** 后台起一次 git；起不来为 undefined，超时杀掉并返回 `"timeout"`。 */
+    run(args) {
         return new Promise((resolve) => {
             let settled = false;
             let timer;
@@ -165,7 +221,7 @@ export class GitInfoWatcher {
             };
             let child;
             try {
-                child = this.spawn("git", ["diff", "--numstat", "HEAD"], {
+                child = this.spawn("git", args, {
                     cwd: this.cwd,
                     env: { ...this.env, GIT_OPTIONAL_LOCKS: "0" },
                 });
@@ -176,7 +232,7 @@ export class GitInfoWatcher {
             }
             timer = setTimeout(() => {
                 child.kill("SIGKILL");
-                done(undefined);
+                done("timeout");
             }, this.timeoutMs);
             timer.unref?.();
             let out = "";
@@ -185,7 +241,7 @@ export class GitInfoWatcher {
                 out += String(chunk);
             });
             child.on("error", () => done(undefined));
-            child.on("close", (code) => done(code === 0 ? parseNumstat(out) : undefined));
+            child.on("close", (code) => done({ code, out }));
         });
     }
 }