Skip to content
Open
4 changes: 3 additions & 1 deletion docs/architecture/update.ja.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@

**セルフアップデータ (`update.ts`)。** デフォルトでは 3 分ごとに npm レジストリをチェックする (`CHECK_INTERVAL_MS`、ノブで上書き可能 #2030; プロセスごとの最初のチェックはスロットリングを無視する)。更新は tarball の展開であり、`npm install` ではない——ユーザーの環境ではライフサイクルスクリプトは決して実行されない。グローバルインストールはインプレースで切り替わる。プラグインモードでは、注入されたコードは HOST プロセス内に存在する: 新しいコードはホストの再起動後にのみ有効になり、壊れた注入はモデルトラフィックを非圧縮の直接通信に劣化させる——パネルのバナーと `/__bili/status` の `attribution` で確認可能 (#3581)。

**バージョンゲート (#6804)。** ロールアウトポリシーの前に、ユーザーに見える 2 つのルールがある: リリースチャネル (`tag="latest"`) にインストールされたプリリリース/一時ビルドは、リリースに自動的に前へ掃き上げられることは決してない——チェックは実行され、新しいバージョンは報告されるが、インストールはされない(`updateTag=dev` のようなプリリリースチャネルは一時ビルドのあいだを依然として移動する)。また、`bili pin [duration]` でピンされたバージョンはチェック専用——新しいバージョンは発見・報告されるが、自動的にインストールされることはなく、ピンは期限で自動的に解除される(`bili unpin` で早期解除)。明示的な `bili update` は両方のゲートを貫通する。ピン状態はマシンレベルのランタイム状態 (`update-pin.ts`) であり、設定キーではない。

**インストールレーン。** グローバル (`npm i -g`、自己更新) · 参照レーン (omp/claude/codex/kimi/zcode/hermes — コピーなし、グローバル dist を指す) · ホストワールド (dsh プロファイルバンドル、opencode/pi ツリー — ホスト自身のチャネルを通じて更新され、グローバル自己更新と、グローバルが実行されない場合のコピー自身の定期的チェックによって駆動される、#1196) · ランチャー (`bili <client>` オーバーレイモード: 永続コピーゼロ)。

**台帳の収束。** デスクトップの dsh プロファイルは、bili が完全に所有する唯一のコピーである; その自己修復は `node_modules/billion-context` を直接切り替えるため、`convergeDshLedger` (`src/dsh-ledger.ts`) は、プロファイルマニフェストの宣言された spec と、ロックファイルに記録された解決結果を同じ操作で移動する (#3496) — コピーのみを移動するライターは、#3224 が検出するドリフトを生み出す。既存のドリフトは明示的な要求時のみ収束する: `bili doctor --fix`。`plugin-install.ts` はホスト自身のチャネル (`dsh plugin add`) のみ駆動し、その隣に第二のコピーをインストールすることは決してしない (#966)。
Expand All @@ -31,7 +33,7 @@

## 主要エントリ

`src/update.ts` (アップデータ — 重要) · `src/advisory.ts` · `src/restart.ts` · `src/plugin-install.ts` · `src/dsh-ledger.ts` · `src/dsh-channel.ts` · `src/pi-channel.ts` · `src/launcher.ts`
`src/update.ts` (アップデータ — 重要) · `src/update-pin.ts` (マシンレベルのバージョンピン, #6804) · `src/advisory.ts` · `src/restart.ts` · `src/plugin-install.ts` · `src/dsh-ledger.ts` · `src/dsh-channel.ts` · `src/pi-channel.ts` · `src/launcher.ts`

## 関連

Expand Down
4 changes: 3 additions & 1 deletion docs/architecture/update.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ Get every copy of bili on a machine to the newest version without bricking anyth

**Self-updater (`update.ts`).** Checks the npm registry every 3 min by default (`CHECK_INTERVAL_MS`, knob-overridable #2030; the first check per process ignores the throttle). Updates are tarball extraction, NOT `npm install` — no lifecycle scripts ever run on user boxes. The global install swaps in place. In plugin mode the injected code lives in the HOST process: new code only takes effect after a host restart, and a broken injection degrades model traffic to uncompressed direct — visible via the panel banner and `/__bili/status` `attribution` (#3581).

**Version gates (#6804).** Before the rollout policy, two user-facing rules: an installed prerelease/temp build on the release channel (`tag="latest"`) is never auto-swept forward to a release — the check runs, the new version is reported, nothing is installed (a prerelease channel like `updateTag=dev` still moves between temp builds); and a version pinned via `bili pin [duration]` is check-only — new versions are discovered and reported but never auto-installed, with the pin lifting itself at expiry (`bili unpin` lifts it early). An explicit `bili update` breaks through both. Pin state is machine-level runtime state in `update-pin.ts`, not a config key.

**Install lanes.** Global (`npm i -g`, self-updating) · reference lanes (omp/claude/codex/kimi/zcode/hermes — no copy, point at the global dist) · host worlds (dsh profile bundle, opencode/pi trees — updated through the host's own channel, driven by the global self-update AND by the copy's own periodic check when no global ever runs, #1196) · launchers (`bili <client>` overlay mode: zero persistent copy).

**Ledger convergence.** The desktop dsh profile is the one copy bili owns outright; its self-heal swaps `node_modules/billion-context` directly, so `convergeDshLedger` (`src/dsh-ledger.ts`) also moves the profile manifest's declared spec AND the lockfile's recorded resolution in the same operation (#3496) — a writer that moves only the copy manufactures the drift #3224 detects. Pre-existing drift converges on explicit demand only: `bili doctor --fix`. `plugin-install.ts` only drives the host's own channel (`dsh plugin add`), never installs a second copy beside it (#966).
Expand All @@ -31,7 +33,7 @@ Human-review tier (§7.4) — no auto-merge; changing `update.ts` requires a NO-

## Key entries

`src/update.ts` (updater — load-bearing) · `src/advisory.ts` · `src/restart.ts` · `src/plugin-install.ts` · `src/dsh-ledger.ts` · `src/dsh-channel.ts` · `src/pi-channel.ts` · `src/launcher.ts`
`src/update.ts` (updater — load-bearing) · `src/update-pin.ts` (per-machine version pin, #6804) · `src/advisory.ts` · `src/restart.ts` · `src/plugin-install.ts` · `src/dsh-ledger.ts` · `src/dsh-channel.ts` · `src/pi-channel.ts` · `src/launcher.ts`

## Related

Expand Down
4 changes: 3 additions & 1 deletion docs/architecture/update.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@

**自更新器(`update.ts`)。** 默认每 3 分钟查一次 npm 注册表(`CHECK_INTERVAL_MS`,旋钮可覆盖 #2030;每进程首查忽略节流)。更新是 tarball 解包,**不是** `npm install`——用户机器上永不跑 lifecycle 脚本。全局安装就地换包。插件模式里注入的代码跑在**宿主进程**中:新代码要宿主重启才生效;注入坏掉则模型流量退化为不压缩直连——面板 banner 与 `/__bili/status` 的 `attribution` 可见(#3581)。

**版本门(#6804)。** 在 rollout 策略之前有两条用户可见规则:发布通道(`tag="latest"`)上安装的预发布/临时构建**永不**被自动扫到正式版——检查照常跑、新版本照常上报、但不安装(预发布通道如 `updateTag=dev` 仍在临时构建之间前进);`bili pin [duration]` 固定的版本为 check-only——新版本照常发现并上报,但永不自动安装,pin 到期自动解除(`bili unpin` 提前解除)。显式 `bili update` 可穿透两条门。pin 状态是机器级运行态(`update-pin.ts`),不是配置键。

**安装车道。** 全局(`npm i -g`,就地自更新) · 引用车道(omp/claude/codex/kimi/zcode/hermes——无拷贝、指全局 dist) · 宿主世界(dsh profile bundle、opencode/pi 树——走宿主自己的通道更新,由全局自更新驱动 + 无全局时拷贝自己的周期检查兜底,#1196) · 启动器(`bili <client>` overlay 模式:零持久拷贝)。

**三账收敛。** 桌面 dsh profile 是 bili 唯一完全自有的拷贝;它的自愈直接换 `node_modules/billion-context`,所以 `convergeDshLedger`(`src/dsh-ledger.ts`)同一操作里还要挪 profile manifest 的声明 spec 与 lockfile 的记录(#3496)——只挪拷贝的写者会亲手造出 #3224 检测的那种漂移。既有漂移只在显式要求时收敛:`bili doctor --fix`。`plugin-install.ts` 只驱动宿主自己的通道(`dsh plugin add`),绝不在旁边装第二份(#966)。
Expand All @@ -31,7 +33,7 @@

## 关键入口

`src/update.ts`(更新器——承重件) · `src/advisory.ts` · `src/restart.ts` · `src/plugin-install.ts` · `src/dsh-ledger.ts` · `src/dsh-channel.ts` · `src/pi-channel.ts` · `src/launcher.ts`
`src/update.ts`(更新器——承重件) · `src/update-pin.ts`(机器级版本 pin,#6804) · `src/advisory.ts` · `src/restart.ts` · `src/plugin-install.ts` · `src/dsh-ledger.ts` · `src/dsh-channel.ts` · `src/pi-channel.ts` · `src/launcher.ts`

## 相关

Expand Down
1 change: 1 addition & 0 deletions reference/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,7 @@ billion-context/
│ ├── external-summary-surface.ts # Tool/schema and client-facing summary contract
│ ├── external-summary-marker.ts # Zero-import marker contract for externally summarized blocks
│ ├── update.ts # Self-updater (load-bearing — no-op release protocol) + install lanes
│ ├── update-pin.ts # Per-machine version pin state for the updater (#6804)
│ ├── advisory.ts # Critical-defect advisory watcher (#1481)
│ ├── plugin-advisory.ts # dsh cost-advisory detection + TTL cache (#2462)
│ ├── host-plugin-notice.ts # Known host-side metering plugin notice + dismiss state (#2861)
Expand Down
88 changes: 83 additions & 5 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,8 @@ import { recordEngineBootstrap } from "./storage/runtime-status.js";
import { configFile as defaultConfigFile, checkNamedConfigRef } from "./paths.js";
import { log as loggerLog } from "./logger.js";
import { createAutoRestartHandler } from "./restart.js";
import { checkForUpdate, startAutoUpdate } from "./update.js";
import { checkForUpdate, startAutoUpdate, forceInstallVersion, findInstallDir } from "./update.js";
import { setPin, clearPin, activePin, parsePinDuration } from "./update-pin.js";
import { registerUpdateActions } from "./server/update-actions.js";
import { startAdvisoryWatcher, getAdvisoryState, advisoryDeferring, advisoryBlocksVersion, advisoryAwaitingFirstCheck } from "./advisory.js";
import { startReleaseNotesWatcher } from "./update-notes.js";
Expand Down Expand Up @@ -134,7 +135,13 @@ Usage:
each (pure-append / mid-stream-rewrite / prefix-stable-miss);
--json machine output, --log FILE correlates [acp-usage]
lines (default <dir>/bili.log), --no-log skips, --session SID filters
bili update check for & install a newer version now
bili update [version] check for & install a newer version now; with a
version argument, installs that exact published
version (release or prerelease/temp build)
bili pin [duration] pin the installed version (1h/12h/1d/7d/forever;
default indefinite) — auto-upgrade becomes
check-only until the pin lifts or bili unpin
bili unpin lift the pin early
bili doctor audit every install lane: versions, owners,
freshness vs registry, running proxy processes
(read-only; --json for machine-readable output);
Expand Down Expand Up @@ -226,7 +233,7 @@ Docs: https://github.com/ranxianglei/billion-context
`;

type Parsed = {
command: "start" | "update" | "doctor" | "help" | "version" | "launch" | "test" | "export" | "plugin-register" | "mcp" | "plugin" | "acp-cache" | "sessions" | "storage" | "pack";
command: "start" | "update" | "pin" | "unpin" | "doctor" | "help" | "version" | "launch" | "test" | "export" | "plugin-register" | "mcp" | "plugin" | "acp-cache" | "sessions" | "storage" | "pack";
client?: ClientName;
clientArgs: string[];
mitmDomains: string[];
Expand Down Expand Up @@ -261,6 +268,8 @@ type Parsed = {
jsonOutput?: boolean;
doctorJson?: boolean;
doctorFix?: boolean;
updateVersion?: string;
pinDuration?: string;
};

export function parseArgs(argv: string[]): Parsed {
Expand Down Expand Up @@ -301,6 +310,8 @@ export function parseArgs(argv: string[]): Parsed {
let jsonOutput = false;
let doctorJson = false;
let doctorFix = false;
let updateVersion: string | undefined;
let pinDuration: string | undefined;

for (let i = 0; i < argv.length; i++) {
const a = argv[i]!;
Expand Down Expand Up @@ -531,6 +542,12 @@ export function parseArgs(argv: string[]): Parsed {
command = "start";
} else if (cmd === "update") {
command = "update";
updateVersion = positional[1];
} else if (cmd === "pin") {
command = "pin";
pinDuration = positional[1];
} else if (cmd === "unpin") {
command = "unpin";
} else if (cmd === "doctor") {
command = "doctor";
} else if (cmd === "export") {
Expand Down Expand Up @@ -656,11 +673,11 @@ export function parseArgs(argv: string[]): Parsed {
}
}

return { command, client, clientArgs, mitmDomains, overrides, exportSelector, exportOutput, exportFull, exportJsonl, registerConversationId, pluginAction, pluginAgent, pluginWithMcp, acpCacheDir, acpCacheLog, acpCacheNoLog, acpCacheSession, sessionsSub, sessionsTarget, sessionsNoVacuum, sessionsApply, sessionsRestoreTarget, storageDays, storageVacuum, storageDryRun, storageSub, storageKeep, storageFrom, jsonOutput, doctorJson, doctorFix, packAction, packSpec, packProject, packForce };
return { command, client, clientArgs, mitmDomains, overrides, exportSelector, exportOutput, exportFull, exportJsonl, registerConversationId, pluginAction, pluginAgent, pluginWithMcp, acpCacheDir, acpCacheLog, acpCacheNoLog, acpCacheSession, sessionsSub, sessionsTarget, sessionsNoVacuum, sessionsApply, sessionsRestoreTarget, storageDays, storageVacuum, storageDryRun, storageSub, storageKeep, storageFrom, jsonOutput, doctorJson, doctorFix, packAction, packSpec, packProject, packForce, updateVersion, pinDuration };
}

export async function main(): Promise<void> {
const { command, client, clientArgs, mitmDomains, overrides, exportSelector, exportOutput, exportFull, exportJsonl, registerConversationId, pluginAction, pluginAgent, pluginWithMcp, acpCacheDir, acpCacheLog, acpCacheNoLog, acpCacheSession, sessionsSub, sessionsTarget, sessionsNoVacuum, sessionsApply, sessionsRestoreTarget, storageDays, storageVacuum, storageDryRun, storageSub, storageKeep, storageFrom, jsonOutput, doctorJson, doctorFix, packAction, packSpec, packProject, packForce } = parseArgs(process.argv.slice(2));
const { command, client, clientArgs, mitmDomains, overrides, exportSelector, exportOutput, exportFull, exportJsonl, registerConversationId, pluginAction, pluginAgent, pluginWithMcp, acpCacheDir, acpCacheLog, acpCacheNoLog, acpCacheSession, sessionsSub, sessionsTarget, sessionsNoVacuum, sessionsApply, sessionsRestoreTarget, storageDays, storageVacuum, storageDryRun, storageSub, storageKeep, storageFrom, jsonOutput, doctorJson, doctorFix, packAction, packSpec, packProject, packForce, updateVersion, pinDuration } = parseArgs(process.argv.slice(2));
// -c/--config fail-fast: a bare NAME that resolves to a missing
// <configDir>/NAME.json names the typo + the available siblings instead of
// silently starting on an empty config (see paths.ts for path behavior).
Expand Down Expand Up @@ -885,19 +902,80 @@ export async function main(): Promise<void> {
}
let updaterResolveProxy: ((url: string) => string | undefined) | undefined;
let updateTag: string | undefined;
let installDir: string | undefined;
try {
const o = loadOptions();
updaterResolveProxy = (url) => resolveProxy(o.routes, o.proxy, url, o.proxyFallback);
updateTag = o.updateTag;
} catch (e) {
console.error(`bili update: config load failed (${String(e)}); updater egress goes direct`);
}
if (updateVersion) {
// #6804: install a specific published version (release or
// prerelease/temp build). Explicit action = user intent, so this
// bypasses the pin and the tag-channel rule.
try {
installDir = await findInstallDir(PACKAGE_NAME);
} catch {
// installDir stays undefined — forceInstallVersion will refuse
}
const result = await forceInstallVersion(
updateVersion,
installDir,
{ packageName: PACKAGE_NAME, currentVersion: VERSION, autoUpdate: true, resolveProxy: updaterResolveProxy, updateTag },
"manual-cli",
"manual",
);
if (result.ok) {
console.log(`bili: installed ${updateVersion}`);
} else {
console.error(`bili update ${updateVersion}: ${result.error ?? "install failed"}`);
process.exit(1);
}
return;
}
await checkForUpdate(
{ packageName: PACKAGE_NAME, currentVersion: VERSION, autoUpdate: true, resolveProxy: updaterResolveProxy, updateTag },
true,
);
return;
}
if (command === "pin") {
// #6804: pin the installed version for a duration. The pin is
// machine-level runtime state — no config file involved.
const version = VERSION;
let durationMs: number | undefined;
if (pinDuration) {
if (pinDuration === "forever") {
// indefinite — no `until` field
} else {
durationMs = parsePinDuration(pinDuration);
if (durationMs === undefined) {
console.error(`bili pin: invalid duration "${pinDuration}" (expected <N>h or <N>d, e.g. 1h, 12h, 1d, 7d, or forever)`);
process.exit(2);
}
}
}
const pin = await setPin(version, durationMs);
if (pin) {
console.log(`bili: pinned ${version}${pin.until !== undefined ? ` until ${new Date(pin.until).toISOString()}` : " (indefinite)"}`);
} else {
console.error("bili pin: failed to write pin state");
process.exit(1);
}
return;
}
if (command === "unpin") {
// #6804: lift the pin early.
const hadPin = (await activePin()) !== undefined;
await clearPin();
if (hadPin) {
console.log("bili: pin lifted");
} else {
console.log("bili: no active pin");
}
return;
}
if (command === "test") {
if (client === "pi") {
await runTestPi({ overrides, mitmDomains });
Expand Down
Loading
Loading