@sema-agent/server 7.119.0 → 7.120.0

package/dist/rules-consent.js

@@ -5,7 +5,7 @@ import { createLogger } from "./observability/logger.js";
 import { MAX_CWD_CHARS } from "./task-cwd.js";
 import { isDirectWritableRuleBehavior } from "./permission-rule-vocab.js";
 import { CONTROL_AND_BIDI_CHARS, hasBidiControls } from "./text-bidi.js";
-import { confirmRuleApproval, RULE_BEHAVIORS, parseRuleText, ruleReachesProgramRun, ruleToolGrammarOf, precheckEditedRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, addPersistedRule, removePersistedRule, effectiveOrThrow, readRowBehavior, } from "@sema-agent/core";
+import { confirmRuleApproval, RULE_BEHAVIORS, parseRuleText, ruleReachesProgramRun, ruleToolGrammarOf, precheckEditedRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, addPersistedRule, removePersistedRule, isValidDurableScope, effectiveOrThrow, readRowBehavior, } from "@sema-agent/core";
 import { buildRulePayloadHash } from "./plugins/permission-rule-store-sql.js";
 export const RULE_IMPORT_TICKET_TTL_MS = 10 * 60_000;
 export const RULE_IMPORT_RETRY_AFTER_SEC = 2;
@@ -57,9 +57,10 @@ export function parseRuleScope(text) {
         return { kind: "global" };
     if (!text.startsWith("project:"))
         return undefined;
-    const root = text.slice("project:".length);
-    return root === "" ? undefined : { kind: "project", root };
+    const scope = { kind: "project", root: text.slice("project:".length) };
+    return isValidDurableScope(scope) ? scope : undefined;
 }
+export const RULE_SCOPE_REFUSAL_SENTENCE = "scope must be 'global' or 'project:<root>' with an absolute root";
 export function sameWireRuleIdentity(row, identity) {
     return row.behavior === identity.behavior && row.rule === identity.rule && row.scope === identity.scope;
 }
@@ -163,7 +164,7 @@ function anchorBatchMembers(members, displayed) {
 function screenLocalImportRow(row) {
     const scope = parseRuleScope(row.scope);
     if (scope === undefined) {
-        return { reason: "scope_unreadable", detail: "scope must be 'global' or 'project:<root>' with a non-empty root" };
+        return { reason: "scope_unreadable", detail: RULE_SCOPE_REFUSAL_SENTENCE };
     }
     if (scope.kind === "project" && hasBidiControls(scope.root)) {
         return {

package/dist/run-local.js

@@ -56,6 +56,7 @@ import { installSecretEnvScrubRecorder } from "./observability/secret-env-scrub.
 import { createHostLspManager } from "./host-lsp-manager.js";
 import { buildDisplaySafeUrl } from "./trace/redact.js";
 import { installOutboundDispatcher } from "./outbound-dispatcher.js";
+import { provisionSemaConfigDir } from "./sema-config-dir.js";
 export function parseArgs(argv) {
     let objective;
     let root;
@@ -325,6 +326,7 @@ export async function runLocal(argv, deps = {}) {
     const memoryEngineIncident = createMemoryEngineIncidentSink({ logger, metrics });
     installSecretEnvScrubRecorder({ logger, metrics });
     logConfigDiagnostics(logger);
+    provisionSemaConfigDir(config, logger);
     installOutboundDispatcher(logger);
     const providerInput = { provider: config.configProvider ?? "local", localDir: root };
     try {

package/dist/sema-config-dir.d.ts

@@ -0,0 +1,19 @@
+import type { Logger } from "./observability/logger.js";
+/** 部署声明的配置根(绝对路径);没声明 ⇒ `undefined`;空串 ⇒ 抛(起服拒,句子点名变量与出路)。纯读 env,不碰文件。**只有 `loadConfig` 调它**
+ *  (结果 = 配置席 `agentConfigDir`);别的读者读那一席。 */
+export declare function declaredSemaConfigDir(env?: NodeJS.ProcessEnv): string | undefined;
+/** 配置根:配置席 `agentConfigDir`(`loadConfig` 铸,声明了的根)在 ⇒ 它;缺席 ⇒ `~/.sema`(与引擎读字面 `~/.sema` 同一处)。不读 env。 */
+export declare function configRootOf(config: {
+    readonly agentConfigDir?: string;
+}): string;
+/**
+ * 起服的**供给动作**(每个入口一次:HTTP 服务第 1 段、`run-local`,都在 logger 建起来之后、任何 Runner 之前):声明了配置根 ⇒ 确保目录在
+ * (不在就建,`0700` —— 本服务本来就往里写 LKG / 缓存 / 店)。没声明 ⇒ 什么都不做(`~/.sema` 由各写者首次写时自建,同 7.119.x)。
+ *
+ * **建不出来不在这里拒**:能不能用由引擎判(`new Runner` 对不是已存在目录的根拒 `config.agent_config_dir_invalid`,起服随之拒),本服务
+ * 只把建目录这件事的失败如实说一行(`sema_config_dir_unprovisioned`,点名变量与 errno)—— 运维在引擎的拒句之前就看到是哪根旋钮、为什么建不出。
+ */
+export declare function provisionSemaConfigDir(config: {
+    readonly agentConfigDir?: string;
+}, logger: Pick<Logger, "warn">): void;
+//# sourceMappingURL=sema-config-dir.d.ts.map

package/dist/sema-config-dir.js

@@ -0,0 +1,33 @@
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+export function declaredSemaConfigDir(env = process.env) {
+    const raw = env.SEMA_CONFIG_DIR;
+    if (raw === undefined)
+        return undefined;
+    if (raw === "") {
+        throw new Error('env SEMA_CONFIG_DIR="" is empty — refusing to start rather than moving the configuration files: up to 7.119.x an empty value meant the process ' +
+            "working directory (the last-known-good config, the skill cache and the scheduler store were kept there), and reading it as unset would move them " +
+            "to ~/.sema without a word. Unset the variable to use ~/.sema, or set it to the directory you mean (to keep the old place, the working directory's path).");
+    }
+    return resolve(raw);
+}
+export function configRootOf(config) {
+    return config.agentConfigDir ?? join(homedir(), ".sema");
+}
+export function provisionSemaConfigDir(config, logger) {
+    const dir = config.agentConfigDir;
+    if (dir === undefined)
+        return;
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    catch (e) {
+        logger.warn("sema_config_dir_unprovisioned", {
+            dir,
+            err: e instanceof Error ? e.message : String(e),
+            note: "SEMA_CONFIG_DIR names a directory this server could not create — the engine refuses a configuration root that is not an existing directory when the first Runner is built, so the boot stops there with the engine's refusal: create the directory, point the variable at one, or unset it (the default is ~/.sema)",
+        });
+    }
+}
+//# sourceMappingURL=sema-config-dir.js.map

package/dist/session-policy-wire.js

@@ -1,4 +1,5 @@
 import { PROTOCOL_TABLE, SessionPolicyError, assertSessionRuleNamesCurrent } from "@sema-agent/core";
+import { displayListEntry } from "./list-entry-display.js";
 import { describeEmptyToolSegment, emptyToolSegmentOf } from "./namespaced-rule-name.js";
 const RULE_FIELDS = {
     toolAllow: true,
@@ -99,17 +100,17 @@ export function describeSessionPermissionRulesProblem(p) {
     }
 }
 function describeUnreachableSessionRuleName(u) {
-    return `${u.field} names "${u.name}", which can never match a tool (${describeEmptyToolSegment(u.ns)}), so nothing was written`;
+    return `${u.field} names ${displayListEntry(u.name)}, which can never match a tool (${describeEmptyToolSegment(u.ns)}), so nothing was written`;
 }
 function describeLegacyToolName(r) {
     const why = r.guidance !== undefined ? ` (${r.guidance})` : "";
     switch (r.verdict) {
         case "retired":
-            return `${r.field} names "${r.name}", a retired tool name${why}; with that rule in place this session could not start another run, so nothing was written — use the current tool name${r.currentName !== undefined ? ` ("${r.currentName}")` : ""}`;
+            return `${r.field} names ${displayListEntry(r.name)}, a retired tool name${why}; with that rule in place this session could not start another run, so nothing was written — use the current tool name${r.currentName !== undefined ? ` (${displayListEntry(r.currentName)})` : ""}`;
         case "unprefixed_namespace":
-            return `${r.field} names "${r.name}", which contains "__" but no protocol prefix; with that rule in place this session could not start another run, so nothing was written — a protocol tool is named ${protocolToolNameShapes()}`;
+            return `${r.field} names ${displayListEntry(r.name)}, which contains "__" but no protocol prefix; with that rule in place this session could not start another run, so nothing was written — a protocol tool is named ${protocolToolNameShapes()}`;
         case "unmintable_segment":
-            return `${r.field} names "${r.name}", which can never match a tool${why}, so nothing was written`;
+            return `${r.field} names ${displayListEntry(r.name)}, which can never match a tool${why}, so nothing was written`;
         default: {
             const unhandled = r.verdict;
             throw new Error(`unhandled legacy tool name verdict: ${JSON.stringify(unhandled)}`);

package/dist/spec-fields.d.ts

@@ -67,10 +67,11 @@ export declare function skillToolListRefusal(skill: Record<string, unknown>): st
  *  白名单外键 fail-loud —— 与 resilience/limits 的「容忍未知键」相反:agents 是能力定义,静默丢字段 =
  *  定义被悄悄削(一个丢掉的 isolation 就是放宽),比 400 更危险,故整条拒。`allowTools` / `denyTools` 本门只判形与条数(`toolList`),
  *  **名字归引擎一只判**(core 7.45.0 #1377 / #1385,开跑前,三来源同判):没有工具能是的拼法(带空白 / 括号形坏 / 不可见字符)、非字符串条目 ⇒ 整 run 拒
- *  `config.agent.unknown_tool`;无人挂的名 ⇒ 不拒、经 `onError`(phase `"config"`)告一次(本仓汇点 `runner_config_advisory`);大小写孪生 / 退役名(`bash`)
- *  **在本仓部署形上也只告不拒** —— 主车道的委派工具带 extraTools 工厂(`capabilities/builtin-tools.ts`),引擎开跑前列不全子代工具池(`agentToolPool` 缺席)就不把
- *  像 `Bash` 的名字判成拼错;引擎给宿主「声明可注入名册」的座后本仓声明名册、这两形回到开跑前拒;
- *  `denyTools` 的 `Tool(content)` ⇒ 整只工具对该子代藏起并告。本仓不在受理口另做名字对照(那会是同一问的第二个判官)。
+ *  `config.agent.unknown_tool`;无人挂的名 ⇒ 不拒、经 `onError`(phase `"config"`)告一次(本仓汇点 `runner_config_advisory`);大小写孪生 / 退役名(`bash` / `BASH`)
+ *  ⇒ 开跑前拒 `config.agent.unknown_tool` —— 主车道的委派工具带 extraTools 工厂,本仓在同一处声明它的名册(core 7.46.0 `extraToolNames`;工厂与名册读同一批工具对象,
+ *  `capabilities/builtin-tools.ts` `createSubagentExtraTools`),引擎因此列得出子代工具池。两张表管子代手里的**全部**工具:委派池与 hands 内建(`Read` / `Edit` / `Write` /
+ *  `Bash` …,core #1430)—— `denyTools:["Write"]` ⇒ 子代没有 `Write`;`allowTools` 只点了调用方工具 ⇒ 子代一只 hands 工具都没有。hands 行之外的引擎工具
+ *  (`Monitor` 等)仍不受这两张表管(引擎已知限制)。`denyTools` 的 `Tool(content)` ⇒ 整只工具对该子代藏起并告。本仓不在受理口另做名字对照(那会是同一问的第二个判官)。
  *  ⚠️ 键判断必须 Object.hasOwn:`in` 走原型链,JSON 里的 "toString"/"constructor"/"__proto__" 键会被
  *  误判为白名单字段,随后 SHAPES[k].ok 不是函数 ⇒ TypeError(fresh 500 / resume 砖;cross-review 复现)。 */
 export declare function taskAgentIssue(item: unknown): string | null;

package/dist/task-settings.d.ts

@@ -373,9 +373,9 @@ export interface FsWriteGateWiring {
      *    存不存在 ⇒ 把哨兵递给它,`deny Edit(src/**)` 会编译成功、指向一个谁也不会写的目录,对真实工作区
      *    的 `<工作区>/src/secret.ts` 这类目标判 allow —— 一条运维亲手写下的收紧规则**静默失效**,方向与写门那条正相反。
      *
-     * ⇒ 本字段**只在真任务根已知时**在场。缺席 ⇒ 规则编译器拿不到 `pathBases.root` ⇒ 需要该基的拼法
-     * (`Edit(src/**)` / `Edit(/etc/**)`)被 core 以 `unsupported.path_base` **整表拒**(→ 422,fail-loud),
-     * 而不是编成一条够不着任何东西的规则。绝对形(`//abs`)与 `~/` 形不需要基,两种部署形都照常编得出。
+     * ⇒ 本字段**只在真任务根已知时**在场。缺席 ⇒ 不声明根 ⇒ 需要该基的拼法(`Edit(src/**)` / `Edit(/etc/**)`)锚在**装入这只策略的那条腿**
+     * 的真根(core 7.46.0 #1383 车 B:锚装一次、在被装入处;`unsupported.path_base` 只剩「声明了一个用不了的基」)—— 哨兵从不被声明成基。
+     * 修前(core ≤7.45)缺席 ⇒ 整表拒(→ 422):沙箱车道上相对 / `/x` 形规则恒 422。绝对形(`//abs`)不需要基;`~/` 形见下一字段。
      */
     taskRoot?: string;
     /**

package/dist/trace/engine-notice-wire.d.ts

@@ -16,7 +16,7 @@
  * 同文件 G1 e2e 的全码扇出夹具、以及契约文档附录 D.3 那张表(含**小节标题里的码数** —— 那道门本批
  * 刚立,立完就在下一次加码时自己咬住了)。
  */
-export declare const ENGINE_NOTICE_WIRE_CODES: readonly ["memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "task.turn_interrupted", "steering.parked_input_blocked", "task.user_steer_undrained", "task.user_followup_undrained", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "task.halt_unconsumed", "task.late_approval", "config.durable_gate_unavailable", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "mcp.injection_dropped", "delegation.ask_unresolvable", "task.interrupt_unconsumed", "approval.read_root_granted", "approval.read_root_grant_rejected", "instructions.source_changed", "session.records_skipped", "server.model_unreachable", "classifier.unavailable", "config.permission_mode_unavailable", "permission.ask_released_by_mode", "permission.read_deny_unapplied", "permission.rule_store_unavailable", "permission.allowed_tool_not_granted", "task.tool_turn_incomplete"];
+export declare const ENGINE_NOTICE_WIRE_CODES: readonly ["memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "task.turn_interrupted", "steering.parked_input_blocked", "task.user_steer_undrained", "task.user_followup_undrained", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "task.halt_unconsumed", "task.late_approval", "config.durable_gate_unavailable", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "mcp.injection_dropped", "delegation.ask_unresolvable", "task.interrupt_unconsumed", "approval.read_root_granted", "approval.read_root_grant_rejected", "instructions.source_changed", "session.records_skipped", "server.model_unreachable", "classifier.unavailable", "config.permission_mode_unavailable", "permission.ask_released_by_mode", "permission.read_deny_unapplied", "permission.rule_store_unavailable", "permission.rule_row_dropped", "permission.allowed_tool_not_granted", "task.tool_turn_incomplete"];
 export type EngineNoticeWireCode = (typeof ENGINE_NOTICE_WIRE_CODES)[number];
 /** 白名单谓词(单点):路由与门都读这一个,不许第二处手抄码串。 */
 export declare function isEngineNoticeWireCode(code: string): code is EngineNoticeWireCode;
@@ -63,10 +63,12 @@ export interface EngineNoticeWireRow {
  */
 export declare function sanitizeNoticeDetail(detail: Record<string, unknown> | undefined): Record<string, unknown>;
 /**
- * 通告 `detail` 里的**规则条目原串**过呈现口(`presentRuleEntry`:剥 C0 / 双向控制符、超长截断)—— 会话流行(经 {@link engineNoticeEventData})
- * 与运维日志行(`boot/runner-deps.ts` 的转发席)同调这一只。其余字段、其余码原样(多行文本不受影响)。
+ * 通告 `detail` 里的**规则文本**换成条目的脱敏原值({@link redactListEntry}:凭据换记号,不加引号、不转义 —— 机读位不是显示面,显示形只属于人读句)。
+ * 会话流行(经 {@link engineNoticeEventData},之后照常过 {@link sanitizeNoticeDetail})与运维日志行(`boot/runner-deps.ts` 的转发席,其余字段逐字)
+ * 同调这一只 ⇒ 两条出路上同一条规则文本逐字节同(会话流行另有 detail 串的 {@link NOTICE_TEXT_MAX} 字上限,超长的那一截只在日志行上),两只码里同一条
+ * 规则文本也同(引擎交来的两形本身一致时 —— `rule_row_dropped` 交的是引擎中和过的形,空白 / 超长的条目两只码今天不同,上游缝)。其余字段、其余码原样。
  */
-export declare function presentNoticeDetail(code: string, detail: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+export declare function redactNoticeRuleText(code: string, detail: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
 export declare function engineNoticeEventData(notice: {
     code: string;
     message: string;

package/dist/trace/engine-notice-wire.js

@@ -1,5 +1,5 @@
 import { redactSecrets } from "./redact.js";
-import { presentRuleEntry } from "../rule-entry-list.js";
+import { redactListEntry } from "../list-entry-display.js";
 import { recordFailOpen } from "../observability/fail-open.js";
 export const ENGINE_NOTICE_WIRE_CODES = [
     "memory.session_polluted",
@@ -34,6 +34,7 @@ export const ENGINE_NOTICE_WIRE_CODES = [
     "permission.ask_released_by_mode",
     "permission.read_deny_unapplied",
     "permission.rule_store_unavailable",
+    "permission.rule_row_dropped",
     "permission.allowed_tool_not_granted",
     "task.tool_turn_incomplete",
 ];
@@ -92,22 +93,28 @@ function sanitizeValue(v, depth) {
     }
     return undefined;
 }
-const RULE_ENTRY_DETAIL_ARRAYS = { "permission.allowed_tool_not_granted": "entries" };
-export function presentNoticeDetail(code, detail) {
-    const key = Object.hasOwn(RULE_ENTRY_DETAIL_ARRAYS, code) ? RULE_ENTRY_DETAIL_ARRAYS[code] : undefined;
-    if (key === undefined || detail === undefined)
+const RULE_TEXT_DETAIL_FIELDS = {
+    "permission.allowed_tool_not_granted": { array: "entries", field: "entry" },
+    "permission.rule_row_dropped": { array: "rows", field: "rule" },
+};
+export function redactNoticeRuleText(code, detail) {
+    const at = Object.hasOwn(RULE_TEXT_DETAIL_FIELDS, code) ? RULE_TEXT_DETAIL_FIELDS[code] : undefined;
+    if (at === undefined || detail === undefined)
         return detail;
-    const list = detail[key];
+    const list = detail[at.array];
     if (!Array.isArray(list))
         return detail;
-    const presented = list.map((item) => item !== null && typeof item === "object" && typeof item.entry === "string" ? { ...item, entry: presentRuleEntry(item.entry) } : item);
-    return { ...detail, [key]: presented };
+    const redacted = list.map((item) => {
+        const text = item !== null && typeof item === "object" ? item[at.field] : undefined;
+        return typeof text === "string" ? { ...item, [at.field]: redactListEntry(text) } : item;
+    });
+    return { ...detail, [at.array]: redacted };
 }
 export function engineNoticeEventData(notice, sessionId, nowMs) {
     return {
         code: notice.code,
         message: redactSecrets(String(notice.message)).slice(0, NOTICE_TEXT_MAX),
-        detail: sanitizeNoticeDetail(presentNoticeDetail(notice.code, notice.detail)),
+        detail: sanitizeNoticeDetail(redactNoticeRuleText(notice.code, notice.detail)),
         sessionId,
         ts: nowMs,
     };

package/dist/trace/self-minted-wire.d.ts

@@ -183,6 +183,20 @@ export declare const SELF_MINTED_WIRE: {
                 readonly attr: "redactErrorMessage";
                 readonly since: "7.108.0";
             };
+            /**
+             * 7.120.0:通告 `detail` 里的规则文本 = 条目的脱敏原值(`list-entry-display.ts` `redactListEntry`,经 `engine-notice-wire.ts` 的
+             * `redactNoticeRuleText`;会话流行与运维日志行同一只;不加引号、不转义 —— 显示形只在人读句里)。修前(7.119.0):本仓手抄的呈现形
+             * (剥 C0 / 双向控制符、超过 160 字截断并标原长),运维日志行不脱敏。钉 test/notice-entry-presentation.test.ts。
+             */
+            readonly "engine_notice permission.allowed_tool_not_granted#detail.entries[].entry": {
+                readonly attr: "redactListEntry";
+                readonly since: "7.120.0";
+            };
+            /** 7.120.0:同上一行同一只写法(码本版入册;引擎交来的是它中和过的规则文本,本仓再过脱敏读口)。钉同上「两只码」组。 */
+            readonly "engine_notice permission.rule_row_dropped#detail.rows[].rule": {
+                readonly attr: "redactListEntry";
+                readonly since: "7.120.0";
+            };
         };
     };
 };

package/dist/trace/self-minted-wire.js

@@ -65,6 +65,8 @@ export const SELF_MINTED_WIRE = {
         members: {
             "GET /v1/runs/:id#result.errorMessage": { attr: "redactErrorMessage", since: "7.57.0" },
             "POST /v1/side-query#errorMessage": { attr: "redactErrorMessage", since: "7.108.0" },
+            "engine_notice permission.allowed_tool_not_granted#detail.entries[].entry": { attr: "redactListEntry", since: "7.120.0" },
+            "engine_notice permission.rule_row_dropped#detail.rows[].rule": { attr: "redactListEntry", since: "7.120.0" },
         },
     },
 };

package/docs/DEVICE-EXECUTOR-PROTOCOL.md

@@ -46,7 +46,9 @@ which version the server speaks before you spend a handshake finding out.
                                                                                       acquire the connection lease
                                       ◀── helloAck { gen, heartbeatIntervalMs,
                                                      maxInflight, pendingInstructions,
-                                                     chunkWatermarks }
+                                                     chunkWatermarks, reconnectGraceMs,
+                                                     cancelGraceMs, chunkGapTimeoutMs,
+                                                     executionCeilingGraceMs }
                                                   … or helloReject { code }
                                       fence: kill/drain everything from older generations
                                       generationAck { gen }  ───────────────────────▶ now (and only now) the
@@ -79,7 +81,7 @@ which version the server speaks before you spend a handshake finding out.
    | `platformOs` | yes | closed set `darwin` \| `linux` (anything else is a `400`; there is no third value) |
    | `platformArch` | no | ≤ 32 bytes |
    | `displayName` | no | ≤ 255 bytes |
-   | `workspaceRoot` | yes | non-empty, ≤ 1024 bytes — the device-side root that path resolution falls back to |
+   | `workspaceRoot` | yes | ≤ 1024 bytes, **an absolute POSIX path** — the device-side root that path resolution and `exec` `cwd` fall back to. Registration refuses anything else (empty, relative, `~/…`) with `400 request.field_invalid`; the same check runs again when a session's execution environment is created, so a device registered with a non-absolute root by an older server is refused there |
 
    `deviceId` and the owner are **not** inputs: the server mints `dev_<26-char ULID>` and takes the owner
    from the verified credential. The response is `200 { deviceId }` and contains no secret of any kind.
@@ -251,6 +253,17 @@ backoff, exponential to a 60 s ceiling, jittered — except for `revoked`, which
 | `gen` | **canonical decimal string** (`"7"`, never `7`, never `"07"`) | the connection generation. Stamp it on every frame you send |
 | `pendingInstructions` | `string[]` | instruction ids the server still considers in flight for you — see §5 R2 |
 | `chunkWatermarks` | `{ [instructionId]: number }` | per instruction, the highest **contiguous** `streamSeq` the server has already accepted. `-1` means "nothing accepted yet" |
+| `reconnectGraceMs` | integer ms | the reconnect grace **in force on this server** (R4): how long in-flight work survives a dropped socket. Deployment-tunable, default 120000 |
+| `cancelGraceMs` | integer ms | the cancel grace in force (R11): how long after a `cancel` is delivered the server waits for your terminal `result`. Default 10000 |
+| `chunkGapTimeoutMs` | integer ms | the chunk-gap timeout in force (R8): how long the server waits for a missing `streamSeq` before failing the instruction. Default 30000 |
+| `executionCeilingGraceMs` | integer ms | the grace added to an instruction's `timeoutMs` before the server gives up and settles it as outcome-unknown (R12: the ceiling is `timeoutMs + executionCeilingGraceMs`). Default 30000 |
+
+The four grace fields are the values the server's own timers are armed with — not documentation defaults. Size
+your reconnect backoff ceiling, your `cancel` answer deadline, your retransmission cadence and your own
+`timeoutMs` enforcement from them. A server that predates them omits all four; treat absence as "not told" and
+fall back to the defaults in the table above, never as zero. For the same reason the published TypeScript type
+(`DeviceHelloAckFrame` from `@sema-agent/server/device-protocol`) declares the four as optional; a server from
+7.120.0 on always sends all four.
 
 `gen` is a string because it is a 64-bit database value; parse it as an integer only if your language can
 hold it, and always **echo the string you were given** rather than re-formatting a number.
@@ -276,7 +289,7 @@ fenced — that half is yours, and it is the reason a device-level single-instan
 
 Send `goodbye { gen, reason, graceMs? }`. The server stops *starting* new dispatches for this connection
 and keeps collecting results for the ones already in flight, then closes the socket after `graceMs` (if you
-omit it, the deployment's reconnect grace — default 120000 ms — is used). Sending `goodbye` does not settle
+omit it, the deployment's reconnect grace — `helloAck.reconnectGraceMs`, default 120000 ms — is used). Sending `goodbye` does not settle
 anything: finish or fail your in-flight instructions properly before you exit.
 
 ⚠️ **`goodbye` is not a hard barrier.** The check happens when a dispatch *enters* the pipeline, and a
@@ -341,9 +354,9 @@ zeros, a plus sign, whitespace or a float form are rejected as malformed.
 | `t` | Fields | Notes |
 |---|---|---|
 | `challenge` | `nonce` string, `protocolVersion` int | first frame the server sends, immediately on open |
-| `helloAck` | `ok`, `heartbeatIntervalMs`, `maxInflight`, `gen`, `pendingInstructions`, `chunkWatermarks` | §1.5 |
+| `helloAck` | `ok`, `heartbeatIntervalMs`, `maxInflight`, `gen`, `pendingInstructions`, `chunkWatermarks`, `reconnectGraceMs`, `cancelGraceMs`, `chunkGapTimeoutMs`, `executionCeilingGraceMs` | §1.5 |
 | `helloReject` | `code`, `minProtocolVersion?` | §1.4; the socket closes right after |
-| `instruction` | `gen`, `instructionId`, `rootSessionId`, `issuedSeq` int, `kind`, `args`, `cwd?`, `shellEnv?`, `timeoutMs` int | one unit of work (§3) |
+| `instruction` | `gen`, `instructionId`, `rootSessionId`, `issuedSeq` int, `kind`, `args`, `cwd?`, `shellEnv?`, `timeoutMs` int | one unit of work (§3). `cwd` appears on `exec` / `execStream` only, and always there (§3.1) |
 | `payload` | `gen`, `instructionId`, `part` (`begin` \| `chunk` \| `commit`), `offset?`, `dataB64?`, `totalLen?`, `sha256?` | the bytes for a write-family instruction (§3.4) |
 | `cancel` | `gen`, `instructionId` | idempotent; answer with a terminal `result` (§5 R11) |
 | `resultAck` | `gen`, `instructionId` | you may release that instruction's buffers |
@@ -416,8 +429,10 @@ silently forgiven: it becomes a gap or a missing terminal, and the instruction e
 ### 3.1 The closed set, its arguments, and the success outcome each one owes
 
 Every `path` in `args` arrives **already absolute and POSIX-normalized** — the server resolved it against
-the session's working directory before sending. `cwd` (when present) is likewise absolute; when it is
-absent, run in the instruction's implied working directory (the resolution base the server already used).
+the session's working directory before sending. `exec` and `execStream` additionally carry `cwd`, which is
+**always present and always absolute**: run the command in exactly that directory. There is no implicit
+base to fall back to, so an executor needs no branch for a missing or relative `cwd`. Every other kind
+carries no `cwd` — its paths are already absolute.
 
 <!-- closed-set: DEVICE_INSTRUCTION_KINDS -->
 
@@ -551,10 +566,37 @@ payload { part: "commit", instructionId, totalLen, sha256 }
 2. on `commit`, verify the length **and** the digest;
 3. only then rename into place — atomically, honouring the instruction's semantics (exclusive create,
    guarded expectation, append);
-4. any failure at any step fails the **whole instruction** and leaves **no half-written file**.
+4. any failure at any step fails the **whole instruction** and leaves **no half-written file** — with one
+   exception, `appendFile`, which is stated next.
 
 `defaultPayloadPartBytes` is 262144, but do not assume it: use `offset` and `totalLen`.
 
+**`appendFile` is the one write that cannot be all-or-nothing.** Steps 1–3 give `writeFile`,
+`writeFileExclusive` and `writeFileGuarded` their guarantee by building the complete file beside the target
+and swapping it in. An append has no such swap: it extends the existing target **in place**, so there is a
+moment after which the target has changed and the instruction has not finished. What POSIX guarantees for an
+`O_APPEND` write is that the position is taken at end-of-file atomically; it does not promise that the payload
+lands in one piece. This protocol therefore asks you to treat `PIPE_BUF` bytes (the POSIX minimum is 512; Linux
+uses 4096) as the largest append you may regard as indivisible — the conservative bound, borrowed from the
+rule POSIX states for pipe writes — and to assume that anything larger can reach the file in several writes,
+interleave with another writer's appends, or stop part-way. So what you answer depends on *when* you fail:
+
+- **The target cannot have been touched yet** — the payload failed its length or digest check, the target
+  could not be opened, your own containment policy refused the path. Answer the ordinary code
+  (`permission_denied`, `not_found`, `is_directory`, `invalid`, …). Nothing changed, so the caller may safely
+  retry.
+- **The target may already have been changed** — a short write, an I/O error part-way through, or the process
+  or the machine going away while the append was running, so that you cannot say how much landed. Answer
+  `outcome_unknown` (§3.3). Never answer `timeout` or `transport_lost` here: both are retryable, and a retry
+  appends the content a second time.
+- **The whole payload was appended.** Answer `{ok:true, kind:"void"}`. Do not report success for a partial
+  append.
+
+The server settles an executor-reported `outcome_unknown` exactly like one it reaches by its own deadlines:
+the caller gets the code `outcome_unknown`, which nothing upstream retries, and your message is kept and
+followed by a fixed sentence telling the model to verify the file's contents before running the append again.
+So make your message specific about what you know (bytes written, where it stopped).
+
 ### 3.5 `writeFileGuarded` and its `expect`
 
 `expect` is `{ canonicalPath: string, fileId?: string, exclusive?: boolean, noFollow?: boolean }`:
@@ -605,7 +647,7 @@ server delivers in order and buffers out-of-order chunks; it acks with `chunkAck
 **cumulative** watermark meaning "everything up to and including this is accepted" (`-1` = nothing yet).
 You may release buffers at or below the watermark.
 
-- A gap that is not filled within the deployment's gap timeout (default 30 s) **fails the instruction**
+- A gap that is not filled within the deployment's gap timeout (`helloAck.chunkGapTimeoutMs`, default 30 s) **fails the instruction**
   with `outcome_unknown` — output is never silently truncated.
 - The reorder buffer is bounded (default 64 entries / 2 MiB decoded). Running far ahead of the watermark
   overflows it and also fails the instruction.
@@ -711,7 +753,7 @@ process — that work is accounted for as "may have run".
 
 **R4 — no reconnect within the grace ⇒ the books close.**
 *Given* the socket dropped with `I` in flight, *when* no connection for this device is established within
-the reconnect grace (default 120 s), *then* `I` settles `outcome_unknown`; a later reconnect does not list
+the reconnect grace (`helloAck.reconnectGraceMs`, default 120 s), *then* `I` settles `outcome_unknown`; a later reconnect does not list
 it, and its `result` is either refused or memo-acked without being believed (§2.4).
 *Executor:* reconnect promptly. If you were offline longer than the grace, your results are no longer
 deliverable — that is not a licence to re-run anything.
@@ -742,7 +784,7 @@ as the original — the first copy the server buffered is the one it will delive
 
 **R8 — a gap is a failure, not a truncation.**
 *Given* the server is waiting for `streamSeq k`, *when* `k` does not arrive within the gap timeout
-(default 30 s) or the reorder buffer overflows (default 64 entries / 2 MiB), *then* `I` fails with
+(`helloAck.chunkGapTimeoutMs`, default 30 s) or the reorder buffer overflows (default 64 entries / 2 MiB), *then* `I` fails with
 `outcome_unknown` — the command already ran, so the result cannot be faithfully reported.
 *Executor:* never skip a `streamSeq`, never renumber after a reconnect, never "compact" a stream.
 
@@ -766,18 +808,18 @@ machine from taking over the lease mid-command; only you can.
 
 **R11 — `cancel` demands a terminal, within a grace.**
 *Given* the server sent `cancel` for `I`, *when* you do not send a terminal `result` within the cancel
-grace (default 10 s, restarted each time the cancel is delivered), *then* `I` settles `outcome_unknown`.
+grace (`helloAck.cancelGraceMs`, default 10 s, restarted each time the cancel is delivered), *then* `I` settles `outcome_unknown`.
 `cancel` is idempotent, is delivered at most once per generation, and **is replayed on the first active
 tick after a same-epoch reconnect** (a cancel written to a socket that then dropped may never have
 arrived).
 *Executor:* treat a repeated `cancel` for the same `I` as a no-op. Answer exactly one terminal:
 `{ok:true, kind:"cancelled", state:"not_started"}` if the work had not begun, `state:"killed"` if you
-killed it, or the work's ordinary outcome if it had already finished. Answer promptly — 10 s is the budget.
+killed it, or the work's ordinary outcome if it had already finished. Answer promptly — `cancelGraceMs` (default 10 s) is the budget.
 
 **R12 — two-layer timeout: yours is authoritative, the server's is a backstop.**
 *Given* an instruction carrying `timeoutMs`, *when* that budget elapses, *then* you must kill the work and
 answer `{ok:false, errorCode:"timeout"}` — that is the only path to the retryable `timeout` word. *When*
-you answer nothing, the server gives up at `timeoutMs` + a grace (default 30 s) and settles
+you answer nothing, the server gives up at `timeoutMs` + `helloAck.executionCeilingGraceMs` (default 30 s) and settles
 `outcome_unknown`; a later result for `I` is then undeliverable.
 *Executor:* enforce `timeoutMs` yourself, and prefer answering late-but-honestly over not answering.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.119.0",
+  "version": "7.120.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -64,7 +64,7 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.45.0",
+    "@sema-agent/core": "7.46.0",
     "@sema-agent/settings-schema": "8.0.0",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",