cofluxd 2.3.0 → 2.4.0

package/executor/runner.js

@@ -0,0 +1,380 @@
+// ../executor/src/runner.ts
+import { spawn } from "node:child_process";
+import { mkdirSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+// ../executor/src/guard.ts
+var PATH_FIELDS = {
+  read: ["path", "filePath", "file"],
+  write: ["path", "filePath", "file"],
+  edit: ["path", "filePath", "file"],
+  ls: ["path", "dir", "directory"],
+  grep: ["path", "dir", "directory"],
+  find: ["path", "dir", "directory"]
+};
+var MUTATING_TOOLS = /* @__PURE__ */ new Set(["write", "edit"]);
+function isInsideWorkspace(workspaceRoot, candidate) {
+  if (!candidate.startsWith("/")) return false;
+  const root = normalizeSegments(workspaceRoot);
+  const target = normalizeSegments(candidate);
+  if (target.length < root.length) return false;
+  return root.every((segment, index) => target[index] === segment);
+}
+function normalizeSegments(path) {
+  const out = [];
+  for (const segment of path.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      out.pop();
+      continue;
+    }
+    out.push(segment);
+  }
+  return out;
+}
+function collectPaths(toolName, input) {
+  if (!input || typeof input !== "object") return [];
+  const fields = PATH_FIELDS[toolName];
+  if (!fields) return [];
+  const record = input;
+  const paths = [];
+  for (const field of fields) {
+    const value = record[field];
+    if (typeof value === "string" && value.length > 0) paths.push(value);
+  }
+  return paths;
+}
+function guardToolCall({ toolName, input, workspaceRoot, writable }) {
+  if (!writable && MUTATING_TOOLS.has(toolName)) {
+    return {
+      block: true,
+      reason: `\u8FD9\u662F\u53EA\u8BFB\u6A21\u5F0F\u7684 executor \u4EFB\u52A1\uFF0C\u4E0D\u80FD\u7528 ${toolName} \u6539\u6587\u4EF6\u3002\u53EA\u505A\u8C03\u67E5\u4E0E\u62A5\u544A\uFF0C\u628A\u7ED3\u8BBA\u5199\u8FDB\u6700\u7EC8\u56DE\u590D\u3002`
+    };
+  }
+  for (const path of collectPaths(toolName, input)) {
+    if (!path.startsWith("/")) {
+      return {
+        block: true,
+        reason: `${toolName} \u7684\u8DEF\u5F84\u5FC5\u987B\u662F\u7EDD\u5BF9\u8DEF\u5F84\uFF08\u6536\u5230 ${path}\uFF09\uFF1B\u5DE5\u4F5C\u533A\u6839\u662F ${workspaceRoot}`
+      };
+    }
+    if (!isInsideWorkspace(workspaceRoot, path)) {
+      return {
+        block: true,
+        reason: `${path} \u5728\u5DE5\u4F5C\u533A\u5916\u3002\u8FD9\u4E2A executor \u4EFB\u52A1\u88AB\u9650\u5236\u5728 ${workspaceRoot} \u4E4B\u5185\uFF0C\u5DE5\u4F5C\u533A\u5916\u7684\u6587\u4EF6\u8BFB\u4E0D\u5230\u4E5F\u6539\u4E0D\u4E86\u3002`
+      };
+    }
+  }
+  return null;
+}
+
+// ../executor/src/sandbox.ts
+function sandboxArgv(profilePath, shell, command) {
+  return ["/usr/bin/sandbox-exec", "-f", profilePath, shell, "-c", command];
+}
+
+// ../executor/src/runner-protocol.ts
+var EXECUTOR_RUNNER_EXIT = {
+  ok: 0,
+  /** Could not start (pi failed to load, the model configuration is unusable, ...). */
+  startupFailed: 10,
+  /** Wound itself down after receiving an abort. */
+  aborted: 11
+};
+
+// ../executor/src/runner.ts
+var parentPort = process.parentPort;
+function send(message) {
+  if (parentPort) parentPort.postMessage(message);
+  else process.send?.(message);
+}
+function onHostMessage(listener) {
+  if (parentPort) parentPort.on("message", (event) => listener(event.data));
+  else process.on("message", (value) => listener(value));
+}
+var transcriptSeq = 0;
+function transcript(kind, text) {
+  if (!text) return;
+  send({ type: "transcript", seq: ++transcriptSeq, kind, text });
+}
+var liveGroups = /* @__PURE__ */ new Set();
+function killGroup(pgid, signal) {
+  try {
+    process.kill(-pgid, signal);
+  } catch {
+  }
+}
+async function stopAllGroups() {
+  for (const pgid of liveGroups) killGroup(pgid, "SIGTERM");
+  if (liveGroups.size === 0) return;
+  await new Promise((resolve) => setTimeout(resolve, 2e3));
+  for (const pgid of liveGroups) killGroup(pgid, "SIGKILL");
+  await new Promise((resolve) => setTimeout(resolve, 200));
+}
+function sandboxedBashOperations(start) {
+  return {
+    exec: (command, cwd, options) => {
+      const [file, ...args] = sandboxArgv(start.sandboxProfilePath, start.shell, command);
+      const child = spawn(file, args, {
+        cwd: start.workspaceRoot,
+        detached: true,
+        // Its own process group, so the whole group can be killed.
+        env: {
+          ...options.env,
+          // The scratch dir, not the system /tmp: that holds other tasks and shared sockets, and the
+          // profile does not allow it anyway.
+          TMPDIR: start.scratchDir,
+          // The credential is never handed down to a tool process.
+          ANTHROPIC_API_KEY: void 0,
+          OPENAI_API_KEY: void 0,
+          GEMINI_API_KEY: void 0,
+          COFLUX_EXECUTOR_RUN_ID: start.runId
+        },
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      const pgid = child.pid;
+      if (typeof pgid === "number") liveGroups.add(pgid);
+      child.stdout?.on("data", (chunk) => options.onData(chunk));
+      child.stderr?.on("data", (chunk) => options.onData(chunk));
+      const onAbort = () => {
+        if (typeof pgid === "number") killGroup(pgid, "SIGTERM");
+      };
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      const timer = options.timeout && options.timeout > 0 ? setTimeout(() => {
+        if (typeof pgid === "number") killGroup(pgid, "SIGKILL");
+      }, options.timeout) : void 0;
+      return new Promise((resolve) => {
+        child.on("close", (code) => {
+          if (timer) clearTimeout(timer);
+          options.signal?.removeEventListener("abort", onAbort);
+          if (typeof pgid === "number") liveGroups.delete(pgid);
+          resolve({ exitCode: code });
+        });
+        child.on("error", () => {
+          if (timer) clearTimeout(timer);
+          if (typeof pgid === "number") liveGroups.delete(pgid);
+          resolve({ exitCode: null });
+        });
+      });
+    }
+  };
+}
+function memoryCredentialStore() {
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    async read(providerId) {
+      return entries.get(providerId);
+    },
+    async list() {
+      return [...entries.keys()].map((providerId) => ({ providerId, type: "api_key" }));
+    },
+    async modify(providerId, fn) {
+      const next = await fn(entries.get(providerId));
+      if (next) entries.set(providerId, next);
+      else entries.delete(providerId);
+      return next;
+    },
+    async delete(providerId) {
+      entries.delete(providerId);
+    }
+  };
+}
+var changedFiles = /* @__PURE__ */ new Set();
+function relativeToWorkspace(root, absolute) {
+  return absolute.startsWith(`${root}/`) ? absolute.slice(root.length + 1) : absolute;
+}
+async function run(start) {
+  const agentDir = `${start.scratchDir}/pi-agent`;
+  mkdirSync(agentDir, { recursive: true });
+  process.env.PI_CODING_AGENT_DIR = agentDir;
+  process.env.PI_CODING_AGENT_SESSION_DIR = `${agentDir}/sessions`;
+  const pi = await import("@earendil-works/pi-coding-agent");
+  const settingsManager = pi.SettingsManager.inMemory();
+  const runtime = await pi.ModelRuntime.create({
+    allowModelNetwork: false,
+    // An in-memory credential store, not the default file at authPath: persistence is the daemon
+    // cache file's job, and a second copy beside it would buy nothing. `setRuntimeApiKey` is already
+    // a memory overlay, so this only makes "nothing is written" structural rather than incidental.
+    credentials: memoryCredentialStore(),
+    authPath: `${agentDir}/auth.json`,
+    modelsPath: `${agentDir}/models.json`,
+    modelsStorePath: `${agentDir}/models-store.json`
+  });
+  for (const provider of start.customProviders) {
+    runtime.registerProvider(provider.id, {
+      name: provider.name || provider.id,
+      baseUrl: provider.baseUrl,
+      api: provider.api,
+      authHeader: provider.authHeader,
+      models: provider.models.map((entry) => ({
+        id: entry.id,
+        name: entry.name || entry.id,
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128e3,
+        maxTokens: 8192
+      }))
+    });
+  }
+  if (start.apiKey) await runtime.setRuntimeApiKey(start.model.provider, start.apiKey);
+  const model = runtime.getModel(start.model.provider, start.model.id);
+  if (!model) {
+    throw new Error(`\u8D26\u53F7\u914D\u7F6E\u91CC\u7684\u6A21\u578B\u4E0D\u53EF\u7528\uFF1A${start.model.provider}/${start.model.id}`);
+  }
+  const guardExtension = {
+    name: "coflux-workspace-guard",
+    hidden: true,
+    factory: (api) => {
+      api.on("tool_call", (event) => {
+        const verdict = guardToolCall({
+          toolName: event.toolName,
+          input: event.input,
+          workspaceRoot: start.workspaceRoot,
+          writable: start.write
+        });
+        if (verdict) {
+          transcript("error", `\u5DF2\u62E6\u4E0B ${event.toolName}\uFF1A${verdict.reason}`);
+          return { block: true, reason: verdict.reason };
+        }
+        if (event.toolName === "write" || event.toolName === "edit") {
+          const path = event.input?.path;
+          if (typeof path === "string") changedFiles.add(relativeToWorkspace(start.workspaceRoot, path));
+        }
+        return void 0;
+      });
+    }
+  };
+  const bashTool = pi.createBashToolDefinition(start.workspaceRoot, {
+    operations: sandboxedBashOperations(start),
+    shellPath: start.shell,
+    // PI_* variables push session metadata into the tools' environment; the executor does not need
+    // them, and that is one information outlet fewer.
+    exposeSessionEnvironment: false
+  });
+  const resourceLoader = new pi.DefaultResourceLoader({
+    cwd: start.workspaceRoot,
+    // Points at this task's scratch dir rather than the user's ~/.pi: their existing state is
+    // neither read nor written.
+    agentDir,
+    settingsManager,
+    noExtensions: true,
+    noSkills: true,
+    noPromptTemplates: true,
+    noThemes: true,
+    noContextFiles: true,
+    systemPrompt: start.systemPrompt,
+    extensionFactories: [guardExtension]
+  });
+  await resourceLoader.reload();
+  const { session } = await pi.createAgentSession({
+    cwd: start.workspaceRoot,
+    agentDir,
+    settingsManager,
+    modelRuntime: runtime,
+    model,
+    sessionManager: pi.SessionManager.inMemory(start.workspaceRoot),
+    // Only the read-oriented built-in tools; bash is ours (same name, arriving through customTools).
+    tools: start.write ? ["read", "edit", "write", "grep", "find", "ls"] : ["read", "grep", "find", "ls"],
+    // This one assertion works around a variance problem in pi's own types: createBashToolDefinition
+    // returns a ToolDefinition<TObject<...>> with a concrete schema, while customTools takes
+    // ToolDefinition<TSchema>, and the two are not covariant. Let this single known point through and
+    // **do not** hoist the assertion onto the whole options object — that would swallow genuinely
+    // structural errors such as resourceLoader (this file once shipped a closed loader that silently
+    // had no effect for exactly that reason).
+    customTools: [bashTool],
+    resourceLoader
+  });
+  send({ type: "running" });
+  let lastAssistantText = "";
+  let lastStopReason = "";
+  let lastErrorMessage = "";
+  session.subscribe((event) => {
+    if (event.type === "message_update") {
+      const inner = event.assistantMessageEvent;
+      if (inner?.type === "text_delta" && inner.delta) lastAssistantText += inner.delta;
+    } else if (event.type === "tool_execution_start") {
+      const name = event.toolName ?? "tool";
+      send({ type: "progress", note: `\u6B63\u5728\u6267\u884C ${name}` });
+      transcript("tool", `\u2192 ${name}`);
+    } else if (event.type === "message_end" || event.type === "turn_end") {
+      const message = event.message ?? {};
+      if (message.stopReason) lastStopReason = message.stopReason;
+      if (message.errorMessage) lastErrorMessage = message.errorMessage;
+      if (lastAssistantText) transcript("assistant", lastAssistantText);
+    }
+  });
+  const timeout = setTimeout(() => void session.abort(), start.timeoutMs);
+  try {
+    await session.prompt(start.prompt);
+  } finally {
+    clearTimeout(timeout);
+  }
+  await stopAllGroups();
+  if (lastStopReason === "error") {
+    transcript("error", lastErrorMessage || "\u6A21\u578B\u8C03\u7528\u5931\u8D25");
+    send({
+      type: "done",
+      outcome: "model_error",
+      summary: lastAssistantText.trim(),
+      changedFiles: [...changedFiles],
+      error: lastErrorMessage || "\u6A21\u578B\u8C03\u7528\u5931\u8D25\uFF0C\u4E14\u672A\u7ED9\u51FA\u539F\u56E0"
+    });
+    return;
+  }
+  if (lastStopReason === "aborted") {
+    send({
+      type: "done",
+      outcome: "cancelled",
+      summary: lastAssistantText.trim(),
+      changedFiles: [...changedFiles],
+      error: lastErrorMessage || "\u4EFB\u52A1\u88AB\u4E2D\u65AD"
+    });
+    return;
+  }
+  if (!lastStopReason) {
+    send({
+      type: "done",
+      outcome: "model_error",
+      summary: "",
+      changedFiles: [...changedFiles],
+      error: "executor \u6CA1\u6709\u4EA7\u51FA\u4EFB\u4F55\u6A21\u578B\u56DE\u590D\uFF1B\u68C0\u67E5\u684C\u9762\u91CC\u914D\u7684 provider \u4E0E\u6A21\u578B\u662F\u5426\u53EF\u7528"
+    });
+    return;
+  }
+  send({
+    type: "done",
+    outcome: "succeeded",
+    summary: lastAssistantText.trim(),
+    changedFiles: [...changedFiles]
+  });
+}
+var aborting = false;
+onHostMessage((message) => {
+  if (message?.type === "abort") {
+    aborting = true;
+    void stopAllGroups().then(() => {
+      send({ type: "done", outcome: "cancelled", summary: "", changedFiles: [...changedFiles], error: "\u5DF2\u88AB\u505C\u6B62" });
+      process.exit(EXECUTOR_RUNNER_EXIT.aborted);
+    });
+    return;
+  }
+  if (message?.type !== "start") return;
+  if (!message.scratchDir) message.scratchDir = mkdtempSync(`${tmpdir()}/coflux-executor-`);
+  run(message).catch(async (error) => {
+    if (aborting) return;
+    await stopAllGroups();
+    const text = error instanceof Error ? error.message : String(error);
+    transcript("error", text);
+    send({
+      type: "done",
+      outcome: text.includes("\u6A21\u578B") || text.includes("model") ? "model_error" : "tool_failed",
+      summary: "",
+      changedFiles: [...changedFiles],
+      error: text
+    });
+  }).finally(() => {
+    if (!aborting) process.exit(EXECUTOR_RUNNER_EXIT.ok);
+  });
+});
+send({ type: "ready" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofluxd",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Coflux 无界面宿主（cofluxd）与统一操作工具（coflux）",
   "type": "module",
   "bin": {
@@ -13,9 +13,14 @@
     "account-client.mjs",
     "release-pubkey.hex",
     "release-trust.mjs",
+    "service-unit.mjs",
     "README.md",
-    "skills"
+    "skills",
+    "executor"
   ],
+  "scripts": {
+    "prepack": "esbuild ../executor/src/host.ts ../executor/src/runner.ts --bundle --platform=node --target=node20 --format=esm --external:@earendil-works/pi-coding-agent --outdir=executor --log-level=warning"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -33,5 +38,11 @@
     "cli",
     "remote-terminal",
     "pty"
-  ]
+  ],
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0"
+  }
 }

package/service-unit.mjs

@@ -0,0 +1,106 @@
+// The launchd / systemd units cofluxd writes, as pure functions of the paths that go into them.
+//
+// Split out of cofluxd.mjs so the one thing that cannot be noticed by using the product can be
+// asserted: whether the executor runtime made it into the unit. A missing variable there is silent
+// — the daemon starts, everything works, and the only symptom is `coflux executor run` reporting
+// much later that this machine has no executor host.
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** The two variables the worker reads; kept identical to `packages/executor/src/env.ts` and
+ * `crates/worker/src/executor_host.rs`. */
+export const EXECUTOR_NODE_ENV = "COFLUX_EXECUTOR_NODE";
+export const EXECUTOR_ENTRY_ENV = "COFLUX_EXECUTOR_ENTRY";
+
+/**
+ * The runtime pair to record in the unit, or `null` when this installation cannot host an executor.
+ *
+ * It is `process.execPath` — the node that is running `cofluxd up` right now — plus the resolved
+ * package entry, both absolute. Deliberately **not** a `PATH` lookup deferred to the daemon: a
+ * launchd job's `PATH` is not the user's, and resolving `node` at start time would mean the
+ * executor silently follows whatever version is installed later.
+ *
+ * `null` is an ordinary outcome, not an error: the desktop-bundled daemon ships Rust and Go
+ * binaries and no JS runtime, and there Coflux.app hosts the executor instead.
+ */
+export function executorRuntime() {
+  const node = process.execPath;
+  if (!node?.startsWith("/")) return null;
+  // Two known layouts, in the order they occur. Published: `prepack` bundles the executor next to
+  // this file with esbuild (see package.json), because `@coflux/executor` is workspace-internal and
+  // never published — the tarball carries the build output, not a registry dependency. Source
+  // checkout: the workspace package's own `tsc` output. Neither present means this installation
+  // cannot host an executor, which is an ordinary outcome.
+  for (const candidate of ["./executor/host.js", "../executor/dist/host.js"]) {
+    const entry = fileURLToPath(new URL(candidate, import.meta.url));
+    if (entry.startsWith("/") && existsSync(entry)) return { node, entry };
+  }
+  return null;
+}
+
+/** Values interpolated into a plist are XML text; a path may legally contain `&` or `<`. */
+function xml(value) {
+  return String(value).replace(/[&<>]/g, (char) => (char === "&" ? "&amp;" : char === "<" ? "&lt;" : "&gt;"));
+}
+
+/**
+ * A systemd `Environment=` value must be one line. A path containing a newline would otherwise turn
+ * the rest of it into a directive of its own, so such a value is dropped rather than escaped —
+ * a real install path never looks like that, and one that does means something is already wrong.
+ */
+function oneLine(value) {
+  return !/[\n\r]/.test(String(value));
+}
+
+export function plistXml({ supervisorBin, home, logFile, executor }) {
+  const variables = [["COFLUX_HOME", home]];
+  if (executor) {
+    variables.push([EXECUTOR_NODE_ENV, executor.node], [EXECUTOR_ENTRY_ENV, executor.entry]);
+  }
+  const entries = variables
+    .map(([key, value]) => `    <key>${xml(key)}</key><string>${xml(value)}</string>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>com.coflux.daemon</string>
+  <key>ProgramArguments</key>
+  <array><string>${xml(supervisorBin)}</string></array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${entries}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${xml(logFile)}</string>
+  <key>StandardErrorPath</key><string>${xml(logFile)}</string>
+</dict>
+</plist>
+`;
+}
+
+export function systemdUnit({ supervisorBin, home, executor }) {
+  const variables = [["COFLUX_HOME", home]];
+  if (executor) {
+    variables.push([EXECUTOR_NODE_ENV, executor.node], [EXECUTOR_ENTRY_ENV, executor.entry]);
+  }
+  const environment = variables
+    .filter(([, value]) => oneLine(value))
+    .map(([key, value]) => `Environment=${key}=${value}`)
+    .join("\n");
+  return `[Unit]
+Description=coflux daemon (supervisor)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+${environment}
+ExecStart=${supervisorBin}
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=default.target
+`;
+}

package/skills/coflux/SKILL.md

@@ -206,8 +206,9 @@ and terminal tabs, long-press on iOS rows and terminal chips) and show no handle
 
 ### When a handle does not resolve
 
-A handle is a prefix, so resolving one can fail in three distinct ways. Each is one readable
-sentence; what matters is which of the three you got:
+A handle is a prefix, so resolving one can fail in three distinct ways — and there is a fourth case
+that is not a resolution failure at all. Each is one readable sentence; what matters is which of the
+four you got:
 
 - **Nothing matches** — no entity of that kind, within the scope that command can see, starts with
   that short id. The handle belongs to another account, to a workspace you are not in, or to
@@ -218,6 +219,12 @@ sentence; what matters is which of the three you got:
 - **Wrong kind** — the handle is well-formed but names a different kind than the command expects
   (a workspace handle where a terminal id goes). The command fails rather than act on an adjacent
   entity; the fix is a handle of the expected kind, never a retry.
+- **It was never a handle** — the `coflux:<kind>:` prefix is **mandatory**. `b6767697` on its own is
+  not a handle, however faithfully it copies the first 8 characters of a real UUID. Nothing rejects
+  it as malformed: it is forwarded untouched as a literal id and fails wherever that id is looked
+  up, **with a message that says nothing about id syntax** — for a device it reads
+  `设备 b6767697 不存在或不属于当前账号`. The three errors above cannot warn you here, because the
+  string never reached the resolver. Write `coflux:device:b6767697`, never `b6767697`.
 
 The scopes differ on purpose: account CLI commands resolve a handle among **the requesting
 account's** entities, while local terminal commands resolve it among the terminals of **the
@@ -433,7 +440,12 @@ to change something, send a new run with a new prompt. So **write the prompt as
 hint**: the executor gets that one string and nothing else — no conversation history, no way to ask
 you what you meant. Say what done looks like and how to check it.
 
-Its boundaries, enforced by a kernel sandbox — count on them, and tell it what it needs up front:
+**Where it exists: macOS only.** Its boundaries are enforced by the macOS kernel sandbox, and there
+is no equivalent on Linux yet, so a Linux machine has no executor and the command says so. On macOS
+it is hosted either by the daemon the user installed from npm or by the desktop app, whichever that
+machine has — you do not choose, and nothing about the command changes either way.
+
+Its boundaries, enforced by that kernel sandbox — count on them, and tell it what it needs up front:
 
 - **Only the originating workspace is writable.** Writes anywhere outside it are refused by the
   kernel. Reads are not restricted, so it can still see system files, toolchains and the rest of the
@@ -446,12 +458,14 @@ Its boundaries, enforced by a kernel sandbox — count on them, and tell it what
 - **One writing executor per workspace at a time.** A second `--write` in the same workspace is
   refused outright rather than queued; read-only runs may go in parallel up to a small cap.
 
-It runs inside the user's desktop app, so it only exists on the machine that app is on, and a run
-ends if the user quits the app, signs out, or stops the machine's terminals (you get a definite
-failure, never a hang). `--timeout <seconds>` caps how long you wait; the default is 30 minutes and
-a timeout cancels the run before failing. The model comes from the user's desktop settings; if they
-have not configured one, the command says so in one line — relay that to the user instead of
-retrying.
+A run ends if the host it is on goes away — the user quits the desktop app, signs out, or stops the
+machine's terminals — and you get a definite failure, never a hang. `--timeout <seconds>` caps how
+long you wait; the default is 30 minutes and a timeout cancels the run before failing. The model
+comes from the user's account-wide executor settings; if they have not configured one, the command
+says so in one line — relay that to the user instead of retrying.
+
+**Images and other files are not an input.** The prompt is a task description with a size cap, not a
+file channel: point at paths inside the workspace instead of trying to hand anything over.
 
 ### Errors from local commands
 
@@ -529,7 +543,9 @@ Success is one line of JSON: `projectId`, `name`, `repoPath`, `defaultBranch`, t
 project, so importing the same repository twice returns the existing one with
 `alreadyImported: true` and creates nothing — re-running it is safe. Failures are one sentence and a
 non-zero exit: "不是 git 仓库" (the path is not inside a repository), "设备离线，无法执行该操作"
-(that device is not connected), and a submitted-but-unfinished import tells you to check
+(that device exists but is not connected), "设备 <id> 不存在或不属于当前账号" (no device of this
+account has that id — fix what you typed rather than go looking at the machine; a bare `b6767697`
+with no `coflux:device:` prefix lands here), and a submitted-but-unfinished import tells you to check
 `coflux project list`.
 
 ### Run one command on another machine
@@ -548,9 +564,11 @@ work, and quoting is yours to get right.
 Its output is not JSON: stdout goes to stdout, stderr goes to stderr (always separate, and each one
 carries an explicit marker if it had to be truncated), and the last line is `# exit=<code>`. **The
 CLI's exit code is the remote command's**, so an ordinary shell test around it works. The CLI's own
-failures — device offline, that device's daemon too old (`cofluxd update && cofluxd restart` there),
-`--cwd` missing or not a directory, the timeout elapsing — are one readable sentence and exit **255**,
-so a remote exit 1 is never confused with "it never ran".
+failures — device offline (it exists and is not connected), no device of this account with that id
+(`设备 <id> 不存在或不属于当前账号`: a mistyped or bare-prefix id, **not** an outage to investigate),
+that device's daemon too old (`cofluxd update && cofluxd restart` there), `--cwd` missing or not a
+directory, the timeout elapsing — are one readable sentence and exit **255**, so a remote exit 1 is
+never confused with "it never ran".
 
 `--cwd` is the only addressing: an absolute path or a `~` prefix, defaulting to the daemon user's
 HOME. To run inside a workspace, pass the `path` from `coflux workspace list --device <deviceId>`.