@turmind/halo 1.6.0 → 1.6.2

package/templates/models/kimi.yaml

@@ -1,10 +1,10 @@
 id: kimi
 runtime: kimi
-revision: 2026100501
+revision: 2026101004
 displayName: Kimi (Moonshot AI)
 displayName_zh: Kimi（月之暗面）
-description: Kimi K3 / K2.6 via OpenAI-compatible chat completions API
-description_zh: Kimi K3 / K2.6，通过 OpenAI 兼容的 chat completions API 调用
+description: Kimi K3 / K2.7 Code / K2.6 via OpenAI-compatible chat completions API
+description_zh: Kimi K3 / K2.7 Code / K2.6，通过 OpenAI 兼容的 chat completions API 调用
 defaultEndpoint: https://api.moonshot.cn/v1
 
 secrets:
@@ -30,6 +30,8 @@ models:
     # Official default output cap; the model can go up to 1M but we don't max out.
     maxOutputTokens: 131072
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       # K3 itself also supports video input, but Halo has no video upload
       # path yet — keep video:false until one exists. Image input is
@@ -53,10 +55,68 @@ models:
         effortPresets:
           - { value: max, label: Max }
 
+  - id: kimi-k2.7-code
+    displayName: Kimi K2.7 Code
+    # Official quickstart: 256K context, max_tokens default 32768.
+    maxOutputTokens: 32768
+    contextWindow: 262144
+    maxContextWindow: 262144
+    compressAt: 0.9
+    capabilities:
+      # Live probe 2026-10-10: named a red 64×64 PNG correctly (base64 data URL).
+      # Video input exists upstream but Halo has no video path (see K3).
+      image: true
+      video: false
+      audio: false
+      promptCaching:
+        # Automatic (prompt_cache_key hint) — probe: turn 2 cached 5376/5622.
+        default: 5m
+        ttlPresets:
+          - { value: 5m, label: 5min }
+      thinking:
+        # Thinking is MANDATORY: thinking:{type:'disabled'} → 400 "only
+        # type=enabled is allowed for this model". kimi-agent's K2.x branch only
+        # sends `disabled` for effort 'disabled', so toggling Off in the form
+        # just omits the field and the model still thinks.
+        defaultEnabled: true
+        default: medium
+        effortPresets:
+          - { value: medium, label: On }
+
+  - id: kimi-k2.7-code-highspeed
+    displayName: Kimi K2.7 Code (highspeed)
+    # Same model as kimi-k2.7-code at ~5-6x output speed (official quickstart:
+    # "与 Kimi K2.7 Code 是同一个模型", 256K context, no non-thinking mode;
+    # capacity "偶有波动"). /v1/models: context_length 262144, image in.
+    maxOutputTokens: 32768
+    contextWindow: 262144
+    maxContextWindow: 262144
+    compressAt: 0.9
+    capabilities:
+      # Live probe 2026-10-10: red 64×64 PNG → "Red"; tool call → tool_calls;
+      # max_tokens 32768 OK. Video: no Halo path (see K3).
+      image: true
+      video: false
+      audio: false
+      promptCaching:
+        # Automatic (prompt_cache_key hint) — probe: turn 2 cached 7016/7016.
+        default: 5m
+        ttlPresets:
+          - { value: 5m, label: 5min }
+      thinking:
+        # MANDATORY, as on kimi-k2.7-code: thinking:{type:'disabled'} → 400
+        # "only type=enabled is allowed for this model".
+        defaultEnabled: true
+        default: medium
+        effortPresets:
+          - { value: medium, label: On }
+
   - id: kimi-k2.6
     displayName: Kimi K2.6
     maxOutputTokens: 32768
     contextWindow: 262144
+    maxContextWindow: 262144
+    compressAt: 0.9
     capabilities:
       # Verified 2026-05-27 via live probes: kimi-k2.6 returns "prepare
       # image failed" on image_url blocks despite past docs claiming

package/templates/models/mimo-token-plan-china.yaml

@@ -1,6 +1,6 @@
 id: mimo-token-plan-china
 runtime: anthropic-messages
-revision: 2026100501
+revision: 2026101002
 displayName: Xiaomi MiMo
 displayName_zh: 小米 MiMo
 description: Xiaomi MiMo via its Anthropic-compatible gateway — Token Plan (China / Singapore / Europe clusters) or pay-as-you-go. Supports 1M context window.
@@ -40,6 +40,8 @@ models:
     displayName: MiMo v2.6 Pro
     maxOutputTokens: 131072
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       image: true
       video: false
@@ -63,6 +65,8 @@ models:
     displayName: MiMo v2.6 Flash
     maxOutputTokens: 131072
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       image: true
       video: false
@@ -87,6 +91,8 @@ models:
     displayName: MiMo v2.5 Pro (deprecated 2026-10-21)
     maxOutputTokens: 131072
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       image: false
       video: false
@@ -110,6 +116,8 @@ models:
     displayName: MiMo v2.5 (deprecated 2026-10-21)
     maxOutputTokens: 131072
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       image: true
       video: false

package/templates/models/minimax.yaml

@@ -1,6 +1,6 @@
 id: minimax
 runtime: minimax
-revision: 2026100501
+revision: 2026101002
 displayName: MiniMax
 displayName_zh: MiniMax
 description: MiniMax M3 / M2.7 family via the Anthropic-compatible Messages API
@@ -43,6 +43,8 @@ models:
     # Official recommended value; hard cap is 524288 but we don't max out.
     maxOutputTokens: 131072
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       # M3 also supports video input, but Halo has no video upload path yet —
       # keep video:false until one exists. Image rides the Anthropic-compatible
@@ -71,6 +73,8 @@ models:
     displayName: MiniMax M2.7
     maxOutputTokens: 16384
     contextWindow: 204800
+    maxContextWindow: 204800
+    compressAt: 0.9
     capabilities:
       image: false
       video: false
@@ -86,7 +90,7 @@ models:
         # minimax-agent.ts maps them via effortToBudget() before sending.
         mode: manual
         defaultEnabled: true
-        default: medium
+        default: high
         defaultBudgetTokens: 8192
         effortPresets:
           - { value: medium, label: Medium }
@@ -96,6 +100,8 @@ models:
     displayName: MiniMax M2.7 Highspeed
     maxOutputTokens: 16384
     contextWindow: 204800
+    maxContextWindow: 204800
+    compressAt: 0.9
     capabilities:
       image: false
       video: false
@@ -107,7 +113,7 @@ models:
       thinking:
         mode: manual
         defaultEnabled: true
-        default: medium
+        default: high
         defaultBudgetTokens: 8192
         effortPresets:
           - { value: medium, label: Medium }

package/templates/models/openai.yaml

@@ -1,51 +1,154 @@
 id: openai
 runtime: openai-chat
-revision: 2026100501
+revision: 2026101005
 displayName: OpenAI (Generic)
 displayName_zh: OpenAI（通用）
 description: Generic OpenAI-compatible chat completions. Use for native OpenAI or any third-party OpenAI-compatible gateway. Capabilities are exposed openly — the user is expected to know what their endpoint supports.
 description_zh: 通用 OpenAI 兼容协议。可用于原生 OpenAI 或任何第三方 OpenAI 兼容网关。能力字段开放给用户自选——由用户对端点能力自行负责。
-defaultEndpoint: https://api.openai.com/v1
-defaultModelId: gpt-4o
+defaultEndpoint: https://bedrock-mantle.us-east-1.api.aws/openai/v1
+defaultModelId: openai.gpt-5.5
 endpointPresets:
+  - https://bedrock-mantle.us-east-1.api.aws/openai/v1
+  - https://bedrock-mantle.us-west-2.api.aws/openai/v1
   - https://api.openai.com/v1
 
 secrets:
   - key: api_key
-    description: API key for the chosen OpenAI-compatible endpoint. Format depends on provider (sk-... for OpenAI, ark-... for Volcengine, etc.)
-    description_zh: 所选 OpenAI 兼容端点的 API Key。前缀格式因厂商而异（OpenAI 是 sk-、火山方舟是 ark- 等）
+    description: API key of the chosen endpoint, sent as a Bearer token — e.g. a Bedrock API key for the Bedrock Mantle presets, or the key your OpenAI-compatible gateway issued (sk-... for OpenAI, ark-... for Volcengine, etc.).
+    description_zh: 所选端点的 API Key（以 Bearer 令牌发送）——例如 Bedrock Mantle 端点用 Bedrock API Key，其他 OpenAI 兼容网关用该网关签发的 Key（OpenAI 是 sk-、火山方舟是 ark- 等）。
     default: <<OPENAI_API_KEY>>
     secret: true
 
-# This provider is a "user-fills-everything" placeholder. The single
-# placeholder model below exists so the registry has something to render
-# in the form's model dropdown — replace its id/endpoint with whatever
-# you actually want to call. capabilities here are deliberately
-# permissive (image/video/audio all true, full thinking + caching
-# presets) so the form doesn't lock anything; if your real endpoint
-# doesn't support, e.g., audio, just don't send audio.
+# Placeholder provider — point it at any OpenAI-compatible endpoint and type
+# the model id that endpoint serves. Custom model ids (anything not listed
+# under `models:`) are treated as fully-permissive in the admin form — the
+# user can flip image/video/audio toggles, pick caching TTL, and set thinking
+# effort or budget. The models census skips this provider; new GPT models are
+# tracked through the aws-bedrock-* providers.
 #
-# Custom model ids (anything not listed under `models:`) are treated as
-# fully-permissive in the admin form — the user can flip image/video/
-# audio toggles, pick caching TTL, and set thinking effort or budget.
+# The listed models (bar the legacy placeholder at the end) are callable out of
+# the box with a Bedrock API key — the default endpoint is Mantle us-east-1:
+# Amazon Bedrock's bedrock-mantle endpoint serves Chat Completions (Bearer
+# auth — what OpenAIAgent sends; the runtime appends /chat/completions).
+# The path prefix is per model: GPT-5.x lives under /openai/v1, gpt-oss under
+# /v1; the wrong one 400s "model ... isn't supported on this route".
+# Source: docs.aws.amazon.com/bedrock/latest/userguide/inference-chat-completions.html
+# and each model card's Programmatic Access table.
+#
+# GPT on Mantle Chat Completions /openai/v1, in-Region (live GET /v1/models
+# 2026-10-10, matches the models-region-compatibility.html bedrock-mantle
+# column), probed through OpenAIAgent 2026-10-10:
+#
+#                    us-east-1   us-west-2   via OpenAIAgent
+#   gpt-6.1-sol          ✓           -       400 (max_tokens)
+#   gpt-6-sol / luna     ✓           -       400 (max_tokens)
+#   gpt-6-astra          ✓           ✓       400 (max_tokens)
+#   gpt-5.6-sol          ✓           -       400 (max_tokens)
+#   gpt-5.6-terra/luna   ✓           ✓       400 (max_tokens)
+#   gpt-5.5              ✓           -       OK
+#   gpt-5.4              ✓           ✓       OK
+#
+# GPT-6.x / 5.6 reject `max_tokens` ("Unsupported parameter ... not supported
+# with this model"; they take max_completion_tokens), which OpenAIAgent always
+# sends — use them through aws-bedrock-mantle / aws-bedrock-openai (Responses
+# API) instead. Each model below carries its own `endpoints:`.
+#
+# Capability notes (Mantle Chat Completions):
+#   - promptCaching: automatic (cached_tokens come back, nothing to send, TTL
+#     undisclosed) — the single 5m preset is a form hint only.
+#   - thinking: reasoning_effort. The validation error lists none / minimal /
+#     low / medium / high / xhigh / max, but `max` 400s "not supported with
+#     this model" on both models, so the presets stop at xhigh. Reasoning
+#     tokens are counted (xhigh 1.4–2x low on the same prompt) but the reply
+#     carries no reasoning text, so no thinking is shown in the UI.
+#   - verbosity: not declared — OpenAIAgent doesn't send it.
 models:
+  # Live-probed 2026-10-10 through OpenAIAgent on us-east-1: tool call →
+  # result → reply OK; us-west-2 → 404 "does not exist". Red PNG → "Red".
+  # Model card: 1,050,000 context / 128,000 output (max_tokens 128001 is
+  # accepted too, so the cap is the card's figure, not a probe). Long-context
+  # rates apply to the whole request past 272K input — hence contextWindow
+  # 272000; maxContextWindow is the real limit.
+  - id: openai.gpt-5.5
+    displayName: GPT-5.5 (Bedrock Mantle)
+    endpoints:
+      - https://bedrock-mantle.us-east-1.api.aws/openai/v1
+    maxOutputTokens: 128000
+    contextWindow: 272000
+    maxContextWindow: 1050000
+    compressAt: 0.9
+    capabilities:
+      image: true
+      video: false
+      audio: false
+      promptCaching:
+        default: 5m
+        ttlPresets:
+          - { value: 5m, label: 5min }
+      thinking:
+        mode: adaptive
+        defaultEnabled: true
+        default: xhigh
+        effortPresets:
+          - { value: low, label: Low }
+          - { value: medium, label: Medium }
+          - { value: high, label: High }
+          - { value: xhigh, label: XHigh }
+
+  # Same surface as GPT-5.5 (probe and model card: 1,050,000 / 128,000), and
+  # the only GPT-5 that OpenAIAgent can drive on us-west-2 — tool round-trip
+  # OK on both regions 2026-10-10.
+  - id: openai.gpt-5.4
+    displayName: GPT-5.4 (Bedrock Mantle)
+    endpoints:
+      - https://bedrock-mantle.us-east-1.api.aws/openai/v1
+      - https://bedrock-mantle.us-west-2.api.aws/openai/v1
+    maxOutputTokens: 128000
+    contextWindow: 272000
+    maxContextWindow: 1050000
+    compressAt: 0.9
+    capabilities:
+      image: true
+      video: false
+      audio: false
+      promptCaching:
+        default: 5m
+        ttlPresets:
+          - { value: 5m, label: 5min }
+      thinking:
+        mode: adaptive
+        defaultEnabled: true
+        default: xhigh
+        effortPresets:
+          - { value: low, label: Low }
+          - { value: medium, label: Medium }
+          - { value: high, label: High }
+          - { value: xhigh, label: XHigh }
+
+  # Legacy placeholder (pre-1.6.1): the default model before the Bedrock Mantle
+  # entries above, kept so agents created on it still resolve their caps and
+  # context. Official API only.
   - id: gpt-4o
     displayName: GPT-4o (placeholder)
+    endpoints:
+      - https://api.openai.com/v1
     maxOutputTokens: 16384
     contextWindow: 128000
+    maxContextWindow: 128000
+    compressAt: 0.9
     capabilities:
       image: true
       video: true
       audio: true
       promptCaching:
-        default: 5m
+        default: 1h
         ttlPresets:
           - { value: 5m, label: 5min }
           - { value: 1h, label: 1hour }
       thinking:
         mode: manual
         defaultEnabled: false
-        default: medium
+        default: high
         defaultBudgetTokens: 8192
         effortPresets:
           - { value: low, label: Low }

package/templates/models/qwen.yaml

@@ -1,12 +1,12 @@
 id: qwen
 runtime: qwen
-revision: 2026100501
+revision: 2026101101
 displayName: Qwen (Aliyun)
 displayName_zh: 通义千问（阿里云）
 description: Qwen3 family on Aliyun Bailian via the Anthropic-compatible Messages API
 description_zh: 阿里云百炼通义千问，通过 Anthropic 兼容的 Messages API 调用
 defaultEndpoint: https://dashscope.aliyuncs.com/apps/anthropic
-defaultModelId: qwen3.7-max
+defaultModelId: qwen3.8-max
 endpointPresets:
   - https://dashscope.aliyuncs.com/apps/anthropic         # Beijing
   - https://dashscope-intl.aliyuncs.com/apps/anthropic    # Singapore
@@ -32,15 +32,110 @@ secrets:
 #     despite docs saying a vision-specific model is required);
 #     qwen3.7-max returned `Unexpected item type in content` (not
 #     supported). So image:false on max, image:true on plus.
-#   - effort presets: pure Halo-side abstraction. Same effort→budget
-#     table as bedrock-agent.ts via qwen-agent.ts's effortToBudget().
+#   - effort presets on the manual (3.7 / 3.6) models: pure Halo-side
+#     abstraction. Same effort→budget table as bedrock-agent.ts via
+#     qwen-agent.ts's effortToBudget().
 #   - temperature range: doc says [0, 2) instead of Anthropic's [0, 1] —
 #     doesn't affect Halo since we don't expose temperature in the form.
+# 2026-10-10 census (help.aliyun.com/zh/model-studio/anthropic-api-messages +
+# the text-generation model guide, both list 3.8-max / 3.8-flash / 3.7-plus as
+# current, 1M context): live-probed on the Anthropic endpoint — manual
+# thinking.budget_tokens still accepted (the doc marks it "即将废弃" in favour
+# of output_config.effort — see 2026-10-11 below), thinking
+# disabled honored, tool_use OK, image OK, cache_control ephemeral hit on
+# turn 2. `ttl: '1h'` is accepted but the entry is still written as
+# ephemeral_5m, so 5m stays the only TTL preset. Max output isn't published
+# per model on these pages — maxOutputTokens stays 16384. 3.7-max / 3.6-plus
+# are not on the deprecation page, kept below the new generation.
+# 2026-10-11 (help.aliyun.com/zh/model-studio/anthropic-api-messages,
+# `output_config.effort`): the doc lists effort values for qwen3.8-max /
+# qwen3.8-flash only — xhigh (default) / medium / low, with max and high
+# folded onto xhigh by the API. So 3.8 is `mode: adaptive`: qwen-agent sends
+# thinking:{type:'enabled'} + output_config.effort. An agent.yaml that already
+# carries an explicit budget_tokens keeps sending it (still accepted). For 3.8
+# the same doc says max_tokens caps reply + thinking together. The 3.7 / 3.6
+# models have no documented effort values → they stay `mode: manual`
+# (budget_tokens). Thinking-field omitted = thinking on for every model here,
+# so off is always sent as type:'disabled'.
 models:
+  - id: qwen3.8-max
+    displayName: Qwen3.8 Max
+    maxOutputTokens: 16384
+    contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
+    capabilities:
+      # Live probe 2026-10-10: named a red 64×64 PNG correctly (3.7-max could not).
+      image: true
+      video: false
+      audio: false
+      promptCaching:
+        default: 5m
+        ttlPresets:
+          - { value: 5m, label: 5min }
+      thinking:
+        mode: adaptive
+        defaultEnabled: true
+        default: xhigh
+        effortPresets:
+          - { value: low, label: Low }
+          - { value: medium, label: Medium }
+          - { value: xhigh, label: XHigh }
+
+  - id: qwen3.7-plus
+    displayName: Qwen3.7 Plus
+    maxOutputTokens: 16384
+    contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
+    capabilities:
+      # Live probe 2026-10-10: named a red 64×64 PNG correctly.
+      image: true
+      video: false
+      audio: false
+      promptCaching:
+        default: 5m
+        ttlPresets:
+          - { value: 5m, label: 5min }
+      thinking:
+        mode: manual
+        defaultEnabled: true
+        default: high
+        defaultBudgetTokens: 8192
+        effortPresets:
+          - { value: medium, label: Medium }
+          - { value: high, label: High }
+
+  - id: qwen3.8-flash
+    displayName: Qwen3.8 Flash
+    maxOutputTokens: 16384
+    contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
+    capabilities:
+      # Live probe 2026-10-10: named a red 64×64 PNG correctly.
+      image: true
+      video: false
+      audio: false
+      promptCaching:
+        default: 5m
+        ttlPresets:
+          - { value: 5m, label: 5min }
+      thinking:
+        mode: adaptive
+        defaultEnabled: true
+        default: xhigh
+        effortPresets:
+          - { value: low, label: Low }
+          - { value: medium, label: Medium }
+          - { value: xhigh, label: XHigh }
+
   - id: qwen3.7-max
     displayName: Qwen3.7 Max
     maxOutputTokens: 16384
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       image: false
       video: false
@@ -54,7 +149,7 @@ models:
         # qwen-agent.ts maps effort labels via effortToBudget().
         mode: manual
         defaultEnabled: true
-        default: medium
+        default: high
         defaultBudgetTokens: 8192
         effortPresets:
           - { value: medium, label: Medium }
@@ -64,6 +159,8 @@ models:
     displayName: Qwen3.6 Plus
     maxOutputTokens: 16384
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       image: true
       video: false
@@ -75,7 +172,7 @@ models:
       thinking:
         mode: manual
         defaultEnabled: true
-        default: medium
+        default: high
         defaultBudgetTokens: 8192
         effortPresets:
           - { value: medium, label: Medium }

package/templates/models/zhipu.yaml

@@ -1,6 +1,6 @@
 id: zhipu
 runtime: zhipu
-revision: 2026100501
+revision: 2026101002
 displayName: Zhipu AI (GLM)
 displayName_zh: 智谱 AI（GLM）
 description: Zhipu GLM-5.x family on open.bigmodel.cn, OpenAI-compatible chat completions
@@ -38,6 +38,8 @@ models:
     displayName: GLM-5.3
     maxOutputTokens: 131072
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       image: false
       video: false
@@ -59,6 +61,8 @@ models:
     displayName: GLM-5.3 Flash
     maxOutputTokens: 131072
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       image: true
       video: false
@@ -79,6 +83,8 @@ models:
     displayName: GLM-5.3 FlashX
     maxOutputTokens: 131072
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       image: true
       video: false
@@ -99,6 +105,8 @@ models:
     displayName: GLM-5.2
     maxOutputTokens: 131072
     contextWindow: 272000
+    maxContextWindow: 1000000
+    compressAt: 0.9
     capabilities:
       image: false
       video: false

package/templates/schema.sql

@@ -25,7 +25,7 @@ CREATE TABLE IF NOT EXISTS agent_sessions (
 CREATE TABLE IF NOT EXISTS disabled_items (
   item_type TEXT NOT NULL CHECK(item_type IN ('agent', 'skill')),
   item_id TEXT NOT NULL,
-  scope TEXT NOT NULL CHECK(scope IN ('global', 'workspace')),
+  scope TEXT NOT NULL CHECK(scope IN ('global', 'workspace', 'extension')),
   disabled_at INTEGER NOT NULL,
   PRIMARY KEY (item_type, item_id, scope)
 );

package/templates/skills/cron/SKILL.md

@@ -61,6 +61,8 @@ Sensible defaults if user didn't say:
 | label      | summarize from prompt + schedule                              |
 | timeout    | leave unset (3600s) — see `--timeout-sec` below               |
 | session    | leave unset (the job's own session) — see `--session` below   |
+| folder     | leave unset (workspace root) — see `--dir` below               |
+| stateless  | off (one session that accumulates) — see `--stateless` below   |
 | prompt     | pass the user's task as-is — the runner prepends an "unattended run, don't ask questions" notice to every fire, so don't add one yourself |
 
 ### 2. Translate the schedule
@@ -77,7 +79,8 @@ Sensible defaults if user didn't say:
 
 **One-shot (at-mode)** — pass `--run-at` instead of `--schedule`. The job
 fires once at that instant and auto-disables. Useful for "remind me at 3pm
-today" or "send the report next Monday morning".
+today" or "send the report next Monday morning". On `update`, passing one
+of the two switches the job's mode and clears the other; never pass both.
 
 | Spoken                            | Flag                                      |
 |-----------------------------------|-------------------------------------------|
@@ -100,8 +103,8 @@ job accumulates its own session (same id as the job; older jobs keep the
 Pass `--session <rootSessionId>`
 only when the user wants the runs to continue a specific conversation (the
 agent then sees that session's history). Rules the user should hear once:
-- the session keeps **its own agent and access level** — `--agent` only
-  applies if the session doesn't exist yet;
+- the session keeps **its own agent and access level** — `--agent` must
+  match an existing session's agent (the helper refuses otherwise);
 - a fire is **skipped** while a turn is already running in that session;
 - if the user chats in that session while a run is in flight, one of the two
   turns may be missing from its history afterwards.
@@ -112,6 +115,29 @@ pass `--session ""` to go back to the job's own session (for an older job
 pinned to `cron-cron-…` that starts a fresh session — leave it alone unless
 the user asks).
 
+**Agent of a stateful job** — once the job's session exists (after its
+first run, or a picked existing session), the job's agent is fixed to that
+session's: `update --agent` to a different one is refused with
+`session <id> already runs agent <A>; …`. To change it, either delete that
+session (admin → Sessions) or switch the job to `--stateless on`. Tell the
+user which; don't pick for them.
+
+**Stateless (`--stateless`, optional)** — a **new session every run**
+(`cron-<id>-<suffix>`), so nothing carries over between runs. Use it for
+tasks that don't need memory ("每天抓一次行情发给我", a fixed report).
+Excludes `--session`. On `update`: `--stateless on` / `--stateless off`
+(clear `--session ""` first if one is set). Old per-run sessions are kept and
+stay reviewable in the Sessions tab. `get` / `list` show
+`effective_session_id: null` for a stateless job.
+
+**Folder (`--dir`, optional)** — the run focuses on a workspace sub-folder:
+its `.halo/INSTRUCTIONS.md` chain joins the prompt and the prompt names the
+working directory (file / shell paths still start at the workspace root).
+Relative to the workspace or absolute; must be an existing directory inside
+it. Applies on every run, including runs that resume the job's session. On
+`update`, `--dir ""` goes back to the workspace root. A folder deleted later
+makes each run fail with `folder not found: …`.
+
 **Active window (`--active-from` / `--active-until`, optional, recurring
 jobs only)** — the schedule fires only inside `[from, until)`; fires outside
 it are skipped silently (no run recorded). "Run now" ignores the window.
@@ -220,6 +246,17 @@ shell_exec: python3 ~/.halo/global/skills/cron/manage-cron.py update <id> \
   --schedule "0 10 * * 1"
 ```
 
+**Stateless job focused on a sub-folder:**
+```bash
+shell_exec: python3 ~/.halo/global/skills/cron/manage-cron.py create \
+  --label "Daily market snapshot" \
+  --workspace /home/ubuntu/sa-agent \
+  --dir reports/market \
+  --stateless \
+  --prompt "Fetch today's index closes and write the summary." \
+  --schedule "0 16 * * 1-5"
+```
+
 **Pause / unpause (no end date in mind):**
 ```bash
 shell_exec: python3 ~/.halo/global/skills/cron/manage-cron.py disable <id>