@runweave/server-linux-x64 0.1.7 → 0.1.9

package/payload/plugins/pi/dist/bridge/runweave-task-supervision.cjs

@@ -0,0 +1,167 @@
+/* global AbortSignal, fetch, module, process, require, URL */
+/* eslint-disable @typescript-eslint/no-require-imports */
+const { spawnSync } = require("node:child_process");
+const os = require("node:os");
+const path = require("node:path");
+const { extractUserPrompt } = require("./runweave-hook-payload.cjs");
+async function requestSupervision({
+  source,
+  stateEndpoint,
+  threadId,
+  terminalPanelId,
+  terminalSessionId,
+  normalizedEvent,
+  token,
+  payload,
+  hookStartedAt,
+  debug = () => {},
+}) {
+  if (
+    source === "codex" &&
+    stateEndpoint &&
+    threadId &&
+    terminalPanelId &&
+    process.env.RUNWEAVE_TERMINAL_AGENT_OPERATION_ID &&
+    [
+      "sessionstart",
+      "userpromptsubmit",
+      "interrupt",
+      "stop",
+      "permissionrequest",
+      "pretooluse",
+      "posttooluse",
+    ].includes(normalizedEvent)
+  ) {
+    const supervisionEndpoint = new URL(
+      "/internal/task-supervision",
+      stateEndpoint,
+    ).toString();
+    const version = !["sessionstart", "userpromptsubmit", "stop"].includes(
+      normalizedEvent,
+    )
+      ? null
+      : spawnSync(
+          process.env.RUNWEAVE_CODEX_EXECUTABLE ||
+            process.env.RUNWEAVE_CODEX_BINARY ||
+            "codex",
+          ["--version"],
+          {
+            encoding: "utf8",
+            timeout: 500,
+            maxBuffer: 1024,
+          },
+        );
+    const event = {
+      sessionstart: "SessionStart",
+      userpromptsubmit: "UserPromptSubmit",
+      interrupt: "Interrupt",
+      stop: "Stop",
+      permissionrequest: "PermissionRequest",
+      pretooluse: "PreToolUse",
+      posttooluse: "PostToolUse",
+    }[normalizedEvent];
+    try {
+      const response = await fetch(supervisionEndpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Runweave-Hook-Token": token,
+        },
+        signal: AbortSignal.timeout(
+          normalizedEvent === "stop"
+            ? Math.max(1, hookStartedAt + 110000 - Date.now())
+            : 700,
+        ),
+        body: JSON.stringify({
+          target: {
+            terminalSessionId,
+            panelId: terminalPanelId,
+            threadId,
+            executorGeneration:
+              process.env.RUNWEAVE_TERMINAL_AGENT_OPERATION_ID,
+          },
+          event,
+          ...(typeof payload.tool_name === "string"
+            ? { toolName: payload.tool_name }
+            : {}),
+          hookVersion: 1,
+          codexVersion: String(version?.stdout || "").trim(),
+          ...(process.env.RUNWEAVE_CODEX_CONFIG_ARGS
+            ? {
+                executionConfig: {
+                  binary:
+                    process.env.RUNWEAVE_CODEX_EXECUTABLE ||
+                    process.env.RUNWEAVE_CODEX_BINARY ||
+                    "codex",
+                  home:
+                    process.env.CODEX_HOME || path.join(os.homedir(), ".codex"),
+                  cwd: process.cwd(),
+                  args: JSON.parse(process.env.RUNWEAVE_CODEX_CONFIG_ARGS),
+                },
+              }
+            : {}),
+          ...(typeof payload.model === "string"
+            ? { executionModel: payload.model }
+            : {}),
+          rawTurnId: payload.turn_id || undefined,
+          ...(normalizedEvent === "stop" &&
+          typeof payload.last_assistant_message === "string"
+            ? { reply: payload.last_assistant_message }
+            : {}),
+          ...(normalizedEvent === "userpromptsubmit"
+            ? { prompt: extractUserPrompt(payload) }
+            : {}),
+          deadline:
+            hookStartedAt + (normalizedEvent === "stop" ? 110000 : 1500),
+        }),
+      });
+      debug("task supervision hook response", {
+        event,
+        status: response.status,
+        version: String(version?.stdout || "").trim(),
+      });
+      if (response.ok)
+        return { result: await response.json(), endpoint: supervisionEndpoint };
+    } catch (error) {
+      debug("task supervision hook unavailable", {
+        event,
+        error: error instanceof Error ? error.name : "unknown",
+      });
+      /* Allow native stop on unavailable supervision; never paste late input. */
+    }
+    // Interrupt has a native 3-second ceiling. It only invalidates decisions.
+  }
+  return null;
+}
+async function writeContinuation(offer, token) {
+  const supervision = offer?.result;
+  if (
+    supervision?.action !== "request-continuation" ||
+    !offer.endpoint ||
+    Date.now() >= supervision.deadline - 1000
+  )
+    return;
+  try {
+    const response = await fetch(`${offer.endpoint}/validate`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Runweave-Hook-Token": token,
+      },
+      signal: AbortSignal.timeout(700),
+      body: JSON.stringify({
+        watchId: supervision.watchId,
+        decisionId: supervision.decisionId,
+        revision: supervision.revision,
+      }),
+    });
+    const result = response.ok ? await response.json() : null;
+    if (result?.valid && Date.now() < supervision.deadline - 500)
+      process.stdout.write(
+        JSON.stringify({ decision: "block", reason: supervision.reason }),
+      );
+  } catch {
+    /* Keep uncertain offers reserved; never replay. */
+  }
+}
+module.exports = { requestSupervision, writeContinuation };

package/payload/plugins/pi/dist/runweave.js

@@ -0,0 +1,316 @@
+// Runweave managed Pi extension. Generated by pnpm agents:build; do not edit.
+
+// plugins/pi/extensions/runweave.ts
+import { spawnSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import { chmod, mkdir, unlink } from "node:fs/promises";
+import { createServer, request } from "node:http";
+import { fileURLToPath } from "node:url";
+
+// packages/agent-bridge/src/transport.ts
+import { spawn } from "node:child_process";
+import path from "node:path";
+function createBridgeTransport(source, bundledBridge) {
+  let delivery = Promise.resolve();
+  return {
+    publish(payload) {
+      const serialized = JSON.stringify(payload);
+      delivery = delivery.then(
+        () => new Promise((resolve) => {
+          const override = process.env.RUNWEAVE_AGENT_BRIDGE_ROOT;
+          const bridge = override ? path.join(override, "runweave-hook-bridge.cjs") : bundledBridge;
+          const child = spawn(
+            process.execPath,
+            [bridge, "--source", source],
+            {
+              stdio: ["pipe", "ignore", "ignore"]
+            }
+          );
+          const timeout = setTimeout(() => child.kill(), 8e3);
+          const finish = () => {
+            clearTimeout(timeout);
+            resolve();
+          };
+          child.stdin.on("error", () => {
+          });
+          child.once("error", finish);
+          child.once("close", finish);
+          child.stdin.end(serialized);
+        })
+      ).catch(() => {
+      });
+    },
+    drain: () => delivery
+  };
+}
+
+// plugins/pi/extensions/runweave.ts
+import path2 from "node:path";
+function runweave(pi) {
+  const terminalSessionId = process.env.RUNWEAVE_TERMINAL_SESSION_ID;
+  const tmuxSocket = process.env.TMUX?.split(",")[0];
+  const pane = process.env.TMUX_PANE;
+  if (!terminalSessionId || !tmuxSocket || !pane) return;
+  let context;
+  let closed = false;
+  let waitingForUI = false;
+  let sequence = 0;
+  let runId = null;
+  let outcome = null;
+  let reply = "";
+  const instanceId = randomUUID();
+  const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+  const transport = createBridgeTransport(
+    "pi",
+    fileURLToPath(
+      new URL("./bridge/runweave-hook-bridge.cjs", import.meta.url)
+    )
+  );
+  let server;
+  let socketPath;
+  let ownsSocket = false;
+  const applied = /* @__PURE__ */ new Map();
+  function publish(ctx, event, hook, extra = {}) {
+    if (closed) return;
+    const fact = {
+      version: 1,
+      sessionId: ctx.sessionManager.getSessionId(),
+      sessionFile: canonicalSessionFile(ctx.sessionManager.getSessionFile()),
+      instanceId,
+      startedAt,
+      sequence: ++sequence,
+      runId,
+      leafId: ctx.sessionManager.getLeafId(),
+      event,
+      outcome
+    };
+    pi.appendEntry("runweave.lifecycle", {
+      ...fact,
+      terminalSessionId,
+      tmuxPaneId: pane,
+      operationId: process.env.RUNWEAVE_TERMINAL_AGENT_OPERATION_ID ?? null,
+      hook,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    transport.publish({
+      hook_event_name: hook,
+      session_id: fact.sessionId,
+      cwd: ctx.cwd,
+      pi: fact,
+      ...extra
+    });
+  }
+  async function openEditor(ctx) {
+    if (!ctx.hasUI) return;
+    const directory = path2.join(
+      "/tmp",
+      `rw-pi-${process.getuid?.() ?? "user"}`
+    );
+    await mkdir(directory, { recursive: true, mode: 448 });
+    await chmod(directory, 448);
+    const key = createHash("sha256").update(`${tmuxSocket}\0${pane}`).digest("hex").slice(0, 24);
+    socketPath = path2.join(directory, `${key}.sock`);
+    const alive = await new Promise((resolve) => {
+      const probe = request({ socketPath, path: "/", timeout: 300 }, (res) => {
+        res.resume();
+        resolve(true);
+      });
+      probe.on("timeout", () => {
+        probe.destroy();
+        resolve(true);
+      });
+      probe.on(
+        "error",
+        (error) => resolve(!["ENOENT", "ECONNREFUSED"].includes(error.code ?? ""))
+      );
+      probe.end();
+    });
+    if (alive) {
+      closed = true;
+      socketPath = void 0;
+      return;
+    }
+    await unlink(socketPath).catch(() => {
+    });
+    server = createServer((req, res) => {
+      let body = "";
+      req.setEncoding("utf8");
+      req.on("data", (part) => {
+        body += part;
+        if (Buffer.byteLength(body) > 1024 * 1024) req.destroy();
+      });
+      req.on("end", () => {
+        try {
+          const input = JSON.parse(body);
+          if (req.method !== "POST" || req.url !== "/editor" || closed || waitingForUI || !context || input.version !== 1 || input.terminalSessionId !== terminalSessionId || input.threadId !== context.sessionManager.getSessionId() || input.instanceId !== instanceId || typeof input.requestId !== "string" || !input.requestId || typeof input.text !== "string")
+            throw new Error("Pi editor identity mismatch");
+          if (applied.has(input.requestId))
+            throw new Error(
+              "Pi editor request was already applied; inspect the terminal before retrying"
+            );
+          if (!applied.has(input.requestId)) {
+            context.ui.setEditorText(input.text);
+            applied.set(input.requestId, input.text);
+            if (applied.size > 64) applied.delete(applied.keys().next().value);
+          }
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({ applied: true }));
+        } catch {
+          res.statusCode = 409;
+          res.end(
+            JSON.stringify({
+              applied: false,
+              error: "Pi editor unavailable or identity changed"
+            })
+          );
+        }
+      });
+    });
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(socketPath, resolve);
+    });
+    ownsSocket = true;
+    await chmod(socketPath, 384);
+  }
+  pi.on("session_start", async (event, ctx) => {
+    if (!ctx.hasUI) {
+      closed = true;
+      return;
+    }
+    try {
+      let directory = path2.dirname(realpathSync(process.argv[1]));
+      let version = "";
+      for (let depth = 0; depth < 5; depth++, directory = path2.dirname(directory)) {
+        try {
+          const pkg = JSON.parse(
+            readFileSync(path2.join(directory, "package.json"), "utf8")
+          );
+          if (pkg.name === "@earendil-works/pi-coding-agent") {
+            version = pkg.version;
+            break;
+          }
+        } catch {
+        }
+      }
+      const [major, minor, patch] = version.split(".").map(Number);
+      if (major !== 0 || minor < 85 || minor === 85 && patch < 1)
+        throw new Error("unsupported");
+    } catch {
+      closed = true;
+      if (ctx.hasUI)
+        ctx.ui.notify(
+          "Runweave requires Pi 0.85.1 or a compatible 0.x release",
+          "warning"
+        );
+      return;
+    }
+    context = ctx;
+    const result = spawnSync(
+      process.env.RUNWEAVE_RUNTIME_TMUX_BINARY || "tmux",
+      [
+        "-S",
+        tmuxSocket,
+        "display-message",
+        "-p",
+        "-t",
+        pane,
+        "#{@runweave_panel_id}"
+      ],
+      { encoding: "utf8", timeout: 1e3 }
+    );
+    const panelId = result.status === 0 ? result.stdout.trim() : "";
+    if (!panelId) {
+      closed = true;
+      return;
+    }
+    process.env.RUNWEAVE_TERMINAL_PANEL_ID = panelId;
+    await openEditor(ctx).catch(
+      () => ctx.ui.notify("Runweave Pi editor unavailable", "warning")
+    );
+    publish(ctx, `session_start:${event.reason}`, "SessionStart", {
+      source: event.reason === "resume" ? "resume" : "startup"
+    });
+  });
+  pi.on("agent_start", (_event, ctx) => {
+    runId ??= randomUUID();
+    outcome = null;
+    reply = "";
+    publish(ctx, "agent_start", "UserPromptSubmit");
+  });
+  pi.on("message_start", (event, ctx) => {
+    if (event.message.role === "user") {
+      const content = event.message.content;
+      const prompt = typeof content === "string" ? content : content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+      publish(ctx, "user_message", "UserPromptSubmit", {
+        prompt: prompt.slice(0, 8e3)
+      });
+    }
+  });
+  pi.on("message_end", (event) => {
+    if (event.message.role !== "assistant") return;
+    outcome = event.message.stopReason === "error" ? "failed" : event.message.stopReason === "aborted" ? "interrupted" : event.message.stopReason === "stop" ? "completed" : null;
+    reply = event.message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n").slice(0, 8e3);
+  });
+  pi.on("agent_settled", (_event, ctx) => {
+    if (!ctx.isIdle() || !runId) return;
+    publish(ctx, "agent_settled", "Stop", { last_assistant_message: reply });
+    runId = null;
+  });
+  pi.on(
+    "tool_execution_start",
+    (event, ctx) => publish(ctx, "tool_execution_start", "PreToolUse", {
+      tool_use_id: event.toolCallId,
+      tool_name: event.toolName
+    })
+  );
+  pi.on(
+    "tool_execution_end",
+    (event, ctx) => publish(ctx, "tool_execution_end", "PostToolUse", {
+      tool_use_id: event.toolCallId,
+      tool_name: event.toolName,
+      is_error: event.isError
+    })
+  );
+  pi.on("ui_prompt_start", (_event, ctx) => {
+    waitingForUI = true;
+    publish(ctx, "ui_prompt_start", "AgentMetadata");
+  });
+  pi.on("ui_prompt_end", (_event, ctx) => {
+    waitingForUI = false;
+    publish(ctx, "ui_prompt_end", "AgentMetadata");
+  });
+  pi.on(
+    "session_tree",
+    (_event, ctx) => publish(ctx, "session_tree", "AgentMetadata")
+  );
+  pi.on(
+    "model_select",
+    (_event, ctx) => publish(ctx, "model_select", "AgentMetadata")
+  );
+  pi.on("session_shutdown", async () => {
+    closed = true;
+    context = void 0;
+    if (server?.listening)
+      await new Promise((resolve) => server.close(() => resolve()));
+    if (ownsSocket && socketPath) await unlink(socketPath).catch(() => {
+    });
+    await transport.drain();
+  });
+}
+function canonicalSessionFile(file) {
+  if (!file) return null;
+  try {
+    return realpathSync(file);
+  } catch {
+    try {
+      return path2.join(realpathSync(path2.dirname(file)), path2.basename(file));
+    } catch {
+      return file;
+    }
+  }
+}
+export {
+  runweave as default
+};

package/payload/plugins/toolkit/.codex-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "toolkit",
+  "version": "0.2.0+codex.d39956a605cbf4666c1ca235b085ba12dd5bef055a944658a64f4da7cb8da081",
+  "description": "Runweave Toolkit plugin for project-specific skills and automation extensions.",
+  "author": {
+    "name": "Runweave"
+  },
+  "keywords": [
+    "runweave",
+    "codex",
+    "skills"
+  ],
+  "hooks": "./hooks.json",
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Runweave Toolkit",
+    "shortDescription": "Runweave-specific toolkit skills and automations.",
+    "longDescription": "A repo-maintained toolkit plugin that packages Runweave-specific skills and related automation surfaces.",
+    "developerName": "Runweave",
+    "category": "Productivity",
+    "capabilities": [
+      "Write",
+      "Interactive"
+    ],
+    "defaultPrompt": [
+      "Use Runweave toolkit skills in this repo.",
+      "Review Runweave repo instructions before coding.",
+      "Run Runweave validation commands for this change."
+    ]
+  }
+}

package/payload/plugins/toolkit/README.md

@@ -0,0 +1,185 @@
+# Runweave Toolkit 插件
+
+这个仓库本地插件是 Runweave Toolkit skills 的唯一规范来源。
+
+Skills 统一维护在：
+
+```text
+plugins/toolkit/skills/<skill-name>/SKILL.md
+```
+
+不要把符号链接作为激活机制。文件存在于这个仓库磁盘上，并不代表当前 Codex 会话已经加载它们。
+
+## 已包含的 Skills
+
+- [`acceptance`](./skills/acceptance/SKILL.md)：统一手机验收材料入口，默认图文，按判断需要提供视频或原始录屏；共用采集、预览与检查流程。
+
+- [`agent-device`](./skills/agent-device/SKILL.md)：iOS 模拟器和真机上的 Agent 交互验收，包含设备预检、独立会话及证据记录。
+- [`update-runweave-ios`](./skills/update-runweave-ios/SKILL.md)：通过统一 CLI 更新 Runweave 到 iPhone，自动递增产品版本和构建号并核对安装和启动；也可脱离 Agent 直接执行命令。
+- [`publish-runweave-server`](./skills/publish-runweave-server/SKILL.md)：发布 Server/CLI npm 新版本，跟进四平台 CI、OIDC、公共安装验证和标签；不自动部署机器。
+- [`update-runweave-backend`](./skills/update-runweave-backend/SKILL.md)：完整更新 Linux 后台及已部署配套服务，检查并补齐 systemd 托管与开机自启，区分运行验证和整机重启验证。
+- `brainstorming`
+- [`ask-first`](./skills/ask-first/SKILL.md)：复杂任务执行前先探索项目，只对齐高返工成本的关键取舍；源自 ByteTech 的 Ask First，支持按需并行探索，沿用已有授权，不强制文档流程。
+- `code-grounded-requirements`
+- [`clear-technical-explanations`](./skills/clear-technical-explanations/SKILL.md)：社区 ASD-STE100 skill 的中文适配，保留 Strict / STE-flavored 两种文本改写模式、语义核对与默认纯文本输出。
+- `daily-doc-maintenance`
+- `daily-refactor`
+- [`daily-record`](./skills/daily-record/SKILL.md)：按日期和项目记录本机 Agent 与飞书本人事项，先筛选本人消息再补上下文，合并文档、聊天和 Agent 的重复事实。
+- `debugging-strategies`
+- `diagnostic-log-debugging`
+- `doc-coauthoring`
+- [`eli5`](./skills/eli5/SKILL.md)：用大图和少量文字生成零基础 HTML 图解；源自 [Thariq Shihipar 的上游技能](https://github.com/anthropics/claude-plugins-community/blob/863e70dc7cff21a2facc749e40a7ecd1a5d19833/eli5/skills/eli5/SKILL.md)，保留核心指令并适配 Codex 主题参数。
+- [`experience`](./skills/experience/SKILL.md)：任意 Git 项目的按需经验检索与结果反馈；按仓库隔离，不依赖项目 `AGENTS.md`。
+- `git-advanced-workflows`
+- `grill-with-docs`
+- `grilling`
+- `github-pr`
+- `handoff`
+- `karpathy-guidelines`
+- `playwright-cli`
+- [`product-exploration`](./skills/product-exploration/SKILL.md)：显式调用的产品探索，默认 30 分钟；只取证报告，不生成测试代码或自动修复。
+- `react-best-practices`
+- `review-only`
+- `runweave-change-validation`
+- `runweave-dev-session`
+- `run-test-cases`
+- `shadcn`
+- `sync-branch-hard-reset`
+- `using-rw`
+- `write-plan`
+- `write-test-cases`
+
+- [youtube-reading](./skills/youtube-reading/SKILL.md)：YouTube 字幕与本机识别、保守校对翻译，交付导读与完整中文正文。
+
+原 [`acceptance-gallery`](./skills/acceptance-gallery/SKILL.md)、[`acceptance-video`](./skills/acceptance-video/SKILL.md) 和 [`recorded-browser-mcp-verification`](./skills/recorded-browser-mcp-verification/SKILL.md) 仅作为显式兼容入口；实现与规则统一维护在 `acceptance/`，已有脚本路径继续转发。
+
+## 随记
+
+[`suiji`](./skills/suiji/SKILL.md) 支持在任意终端搜索随记或读取交接指令，完整结果在当前终端交付，随记只追加简短最终摘要，默认不上传图片或文档；用户确认后可完成待办。该目录可单独安装，Python 客户端不依赖本仓库或 Runweave Backend。
+
+## 验证
+
+以下命令从仓库根目录执行。
+
+验证插件 manifest 和打包的 skills：
+
+```bash
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+uv run --with pyyaml python "$CODEX_HOME/skills/.system/plugin-creator/scripts/validate_plugin.py" \
+  plugins/toolkit
+```
+
+验证单个 skill（使用项目内入口，官方校验器保持只读）：
+
+```bash
+pnpm toolkit:validate -- plugins/toolkit/skills/github-pr
+```
+
+入口需要 `uv`，从 `CODEX_HOME`（默认 `~/.codex`）定位官方 `skill-creator` 校验器，在隔离环境准备 PyYAML 后调用；不修改全局 Python 依赖、官方技能、项目 Python 环境或提交钩子。首次准备依赖可能需要网络。正常校验的输出与退出码原样保留：0 为通过，1 为内容不合格；启动、依赖准备或执行异常返回 2，不能当作内容校验失败。
+
+验证每个 skill（任一失败立即停止，避免后续成功掩盖失败）：
+
+```bash
+for skill_dir in plugins/toolkit/skills/*; do
+  [ -d "$skill_dir" ] || continue
+  pnpm toolkit:validate -- "$skill_dir" || exit "$?"
+done
+```
+
+## 本地安装
+
+注册仓库本地 marketplace：
+
+```bash
+codex plugin marketplace add .
+```
+
+读取 marketplace 名称并安装插件：
+
+```bash
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+MARKETPLACE_NAME="$(python3 "$CODEX_HOME/skills/.system/plugin-creator/scripts/read_marketplace_name.py" \
+  --marketplace-path .agents/plugins/marketplace.json)"
+codex plugin add "toolkit@$MARKETPLACE_NAME"
+```
+
+`experience` 是可选 skill：Codex 用户主动安装 Toolkit 后发现它；Pi 用户可单独安装同一源码目录：
+
+```bash
+pi install /absolute/path/to/browser-viewer/plugins/toolkit/skills/experience
+```
+
+该目录自带 Pi package manifest，不依赖构建或 Electron 分发副本。桌面启动和 Pi hooks 安装器
+不会安装、升级或覆盖这个 skill；未安装就不提供该检索入口，不做自动补装。
+项目无需写入提示文件。已有 CLI 和认证连接可用后，Agent 按问题选择 skill，不在启动时强制检索。
+
+重新安装后，在新的 Codex 线程中验证 skill 加载。不要依赖当前线程热加载插件 skills。
+
+## 更新流程
+
+开发过程中更新这个本地插件时，使用 cachebuster helper，不要手动编辑 marketplace 元数据：
+
+```bash
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+python3 "$CODEX_HOME/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py" \
+  plugins/toolkit
+```
+
+然后读取 marketplace 名称并重新安装插件：
+
+```bash
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+MARKETPLACE_NAME="$(python3 "$CODEX_HOME/skills/.system/plugin-creator/scripts/read_marketplace_name.py" \
+  --marketplace-path .agents/plugins/marketplace.json)"
+codex plugin add "toolkit@$MARKETPLACE_NAME"
+```
+
+Hooks 运行时代码放在 `plugins/toolkit/hooks/`。
+
+- Codex hook 配置由 `plugins/toolkit/.codex-plugin/plugin.json` 的 `hooks` 字段显式指向
+  `plugins/toolkit/hooks.json`，随 `toolkit@runweave` 和 `toolkit@local` 安装进入插件缓存。
+- 不要只在插件根目录放置 `hooks.json` 而不更新 manifest；新启动的 Codex 进程不会因为
+  该文件存在就自动执行 hook。
+- Electron 安装器会从同步后的 `electron/resources/hooks/` 运行副本安装 launcher 与
+  兼容/清理层，旧的 Codex 全局 hooks 与 Trae 全局 TOML hook 会被去重清理。
+
+## 自动更新
+
+提交时如果 staged diff 包含 `plugins/toolkit` 或 `.agents/plugins/marketplace.json`，pre-commit 会先执行：
+
+```bash
+pnpm toolkit:sync:staged
+```
+
+该命令会同步 toolkit hook 资产到 Electron resources，并将插件安装到 Codex 的
+`toolkit@runweave` 与 Trae CLI 的 `toolkit@local`。分发版本由实际文件内容决定，
+与同步时间、工作区路径无关；相同内容跳过重复安装，不改写源码 manifest 的版本。
+插件 `hooks.json` 与 hook 运行副本写回本次提交。需要跳过本机插件安装时，可设置：
+
+三个工作区共用 `$CODEX_HOME/plugins/sources/runweave` 下的固定 marketplace 和不可变
+内容版本，同步安装通过本机锁串行执行，不再将全局 marketplace 来回切换到不同工作区。
+自动提交只由主工作区发布全局插件；linked worktree 的提交仅生成并暂存本地资产，
+避免旧分支回退全局插件。需要主动发布某个工作区时，在该工作区运行 `pnpm toolkit:sync`。
+包内只包含 Git 跟踪或未忽略的分发文件，不包含 `.playwright-cli` 等本地运行产物。
+真实插件内容变化仍需在 Codex 的 `/hooks` 中审核；同步命令不修改任何 Hook 信任记录。
+
+Codex 线程启动后会保存已加载 skill 的缓存绝对路径。`pnpm toolkit:sync` 会在重新安装
+Codex 插件前快照现有 Toolkit 缓存，并在安装后恢复被历史会话引用过的旧 cachebuster
+真实目录，避免已经打开的线程继续调用旧 skill 时遇到 `SKILL.md` 路径不存在。新线程仍会
+加载最新版本。
+
+```bash
+RUNWEAVE_SKIP_TOOLKIT_PLUGIN_SYNC=1 git commit
+```
+
+也可以手动执行完整同步：
+
+```bash
+pnpm toolkit:sync
+```
+
+Hook 链路的真实验证命令：
+
+```bash
+pnpm toolkit:verify-hooks
+```