mixdog 1.1.1 → 1.2.0

package/README.md

@@ -139,6 +139,7 @@ savings come from.
 - [Benchmarks](benchmarks/terminal-bench-2.1/)
 - [Code Tidy](docs/code-tidy.md)
 - [Git & GitHub](docs/git-github-integration.md)
+- [SSH servers](docs/ssh-remote.md) (Korean, with an English summary)
 - [Language servers](docs/language-servers.md)
 - [Office runtime](src/runtime/office/README.md)
 - [Development, configuration, and testing](docs/development.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "private": false,
   "type": "module",
   "description": "Open-source coding agent that matches Codex on Terminal-Bench 2.1 with 63% fewer tokens.",
@@ -156,6 +156,7 @@
     "@formulajs/formulajs": "^4.6.1",
     "@google/generative-ai": "^0.24.1",
     "@huggingface/transformers": "^4.2.0",
+    "@img/sharp-wasm32": "0.35.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "^0.6.0",
     "@napi-rs/canvas": "^1.0.8",
@@ -203,7 +204,6 @@
     "eslint-scope": "^9.1.2",
     "lucide-static": "^1.41.0"
   },
-  "main": "index.js",
   "directories": {
     "doc": "docs"
   },

package/scripts/lib/run-node-tests.mjs

@@ -132,6 +132,15 @@ export function testIsolationEnv(scratchDir) {
 export const DEFAULT_TEST_TIMEOUT_MS = 120_000;
 export const LONG_TEST_TIMEOUT_MS = 600_000;
 
+/** Per-file timeout default for explicitly named files: a `.slow`/`.live`/
+ *  `.electron` test file keeps its lane's long bound (scripts/test.mjs laneOf)
+ *  even when run outside the lane runner. */
+export function explicitFilesTimeoutMs(fileArgs) {
+  return fileArgs.some((arg) => /\.(slow|live|electron)\.test\.mjs$/.test(String(arg)))
+    ? LONG_TEST_TIMEOUT_MS
+    : DEFAULT_TEST_TIMEOUT_MS;
+}
+
 // A batch that has not exited by then is killed with its process tree and
 // fails the run; MIXDOG_TEST_BATCH_TIMEOUT_MS overrides the default.
 const DEFAULT_BATCH_TIMEOUT_MS = 60 * 60 * 1000;

package/scripts/prune-desktop-runtime.mjs

@@ -190,6 +190,9 @@ async function prunePdfRuntime(nodeModules) {
 }
 
 async function pruneSharpWasmFallback(nodeModules, target) {
+  // The Linux daemon runs on Electron, whose system GLib breaks the native
+  // addon; src/runtime/shared/sharp-electron-linux.mjs routes it to wasm.
+  if (target.platform === 'linux') return false;
   const imgRoot = join(nodeModules, '@img');
   let packages;
   try {

package/scripts/release-paths.mjs

@@ -2,7 +2,7 @@
 // Single source of truth for CI/CD path selection.
 //
 // Consumers:
-//   - .github/workflows/release-gate.yml  → `node scripts/release-paths.mjs desktop-regex|runtime-regex`
+//   - .github/workflows/release-gate.yml  → `node scripts/release-paths.mjs desktop-regex|runtime-regex|patch-regex|history-regex|mobile-regex`
 //     (grep -E patterns selecting which incremental gates a change requires)
 //   - .github/workflows/deploy.yml        → `import { RELEASE_CRITICAL_PATHS }`
 //     (git diff paths whose change invalidates the previous release's
@@ -47,6 +47,24 @@ const PATCH_GATE_FILES = [
   ...GATE_SELECTION_SOURCES,
 ];
 
+// The shipped-definition history is generated from git history of the agent,
+// workflow, output-style and bundled-skill trees (scripts/build-shipped-history.mjs)
+// and committed under src/defaults/. Release re-checks it, so the gate checks
+// it first instead of letting a stale file fail the deploy late.
+const HISTORY_GATE_PREFIXES = ['src/agents/', 'src/workflows/', 'src/output-styles/', 'src/defaults/'];
+const HISTORY_GATE_FILES = [
+  'scripts/build-shipped-history.mjs',
+  'src/runtime/shared/shipped-definitions.mjs',
+  '.github/workflows/release-gate.yml',
+  ...GATE_SELECTION_SOURCES,
+];
+
+// The mobile release scripts (Python) carry unittest suites that no Node lane
+// discovers; they run when those scripts or the mobile workflows change.
+const MOBILE_GATE_PREFIXES = ['apps/mobile/scripts/'];
+const MOBILE_WORKFLOW_PATTERN = '\\.github/workflows/mobile-[^/]*\\.yml$';
+const MOBILE_GATE_FILES = ['.github/workflows/release-gate.yml', ...GATE_SELECTION_SOURCES];
+
 // deploy.yml plan: paths whose change since the published release tag marks
 // the default lane as unverified.
 export const RELEASE_CRITICAL_PATHS = ['native', 'scripts', 'src', ...PACKAGE_MANIFESTS];
@@ -77,14 +95,33 @@ export function patchGateRegex() {
   ].join('|')})`;
 }
 
+export function historyGateRegex() {
+  return `^(${[
+    ...HISTORY_GATE_PREFIXES.map(escapeRegex),
+    ...HISTORY_GATE_FILES.map((file) => `${escapeRegex(file)}$`),
+  ].join('|')})`;
+}
+
+export function mobileGateRegex() {
+  return `^(${[
+    ...MOBILE_GATE_PREFIXES.map(escapeRegex),
+    ...MOBILE_GATE_FILES.map((file) => `${escapeRegex(file)}$`),
+    MOBILE_WORKFLOW_PATTERN,
+  ].join('|')})`;
+}
+
 const mode = process.argv[2];
 if (mode) {
   if (mode === 'desktop-regex') process.stdout.write(`${desktopGateRegex()}\n`);
   else if (mode === 'runtime-regex') process.stdout.write(`${runtimeGateRegex()}\n`);
   else if (mode === 'patch-regex') process.stdout.write(`${patchGateRegex()}\n`);
+  else if (mode === 'history-regex') process.stdout.write(`${historyGateRegex()}\n`);
+  else if (mode === 'mobile-regex') process.stdout.write(`${mobileGateRegex()}\n`);
   else if (mode === 'critical-paths') process.stdout.write(`${RELEASE_CRITICAL_PATHS.join('\n')}\n`);
   else {
-    process.stderr.write(`unknown mode: ${mode} (expected desktop-regex|runtime-regex|patch-regex|critical-paths)\n`);
+    process.stderr.write(
+      `unknown mode: ${mode} (expected desktop-regex|runtime-regex|patch-regex|history-regex|mobile-regex|critical-paths)\n`
+    );
     process.exit(1);
   }
 }

package/scripts/test-direct.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Explicit Node test options and file paths, without discovery or lane filters.
-import { runNodeTests } from './lib/run-node-tests.mjs';
+import { explicitFilesTimeoutMs, runNodeTests } from './lib/run-node-tests.mjs';
 
 const argv = process.argv.slice(2);
 // The same defaults as scripts/test.mjs: `mock.module` is still flag-gated on
@@ -17,5 +17,7 @@ await runNodeTests(
     '--test',
     ...unlessGiven('--test-force-exit'),
   ],
-  argv
+  argv,
+  // A named slow-lane file keeps the slow lane's per-file bound.
+  { testTimeoutMs: explicitFilesTimeoutMs(argv) }
 );

package/src/defaults/shipped-history.json

@@ -321,9 +321,11 @@
       "0f14ba0a3d8b3896b717dc144bbe49a4",
       "1c317db86e1ff80a5c4102e09e36f5fb",
       "242f11864abdef90fa0cc9cb4599a579",
+      "29a347c4d3a2f773fa92c627260301ba",
       "336ced846a9e4f774cbb109417856c3b",
       "3f72247651ad9d777b6754bfd46732aa",
       "50bdf35d06913236855080fdea6b50dc",
+      "5b4586a44104b26ae7dd45da101079bf",
       "6101786127a1e68778eafcd2bf2c9ce0",
       "6711dbc9d84023b8eabfa928b8d33d18",
       "6f9e9338f560fa9acd839a67b5e2d1cc",
@@ -339,6 +341,7 @@
       "e04e6abe9a54e7d07b37f8fc32b5ad30",
       "e38d606df69865a9cf1cc48386535e8b",
       "e5ac8ea16905815e36e88d883195a617",
+      "e9b89f9193bd9d9c80ba6cf4419e58ff",
       "feabe973080344c4d52787a96043ab68",
       "ff18ac1a9f5961925aec27ffb870bae0"
     ],
@@ -360,6 +363,9 @@
       "f209e75b6ea0360929516a713474ad71",
       "fe0512acbb2fc8f80c5961b9f44aa5e2"
     ],
+    "visualize": [
+      "f65924f0691284ad31000469a9855b62"
+    ],
     "xlsx": [
       "0deebbdd009b0a0941ca4b0833dbe7f6",
       "10778ab8e1e2f7929895c034fef9ac41",

package/src/defaults/skills/setup/references/actions.md

@@ -6,7 +6,7 @@ Read this when choosing a `setup` mutation.
 
 - `status` reads one domain: summary, model, agents, workflow, websearch,
   output-style, profile, autoclear, compaction, memory, features, local-provider, shell,
-  providers, mcp, skills, plugins, update, onboarding, capabilities, developer,
+  providers, mcp, skills, plugins, update, onboarding, worktree, capabilities, developer,
   desktop, appearance, projects, connection, schedules, webhooks, hooks, or
   media.
 - `open` navigates to a supported UI surface. Read `surfaces.md` for targets and
@@ -42,6 +42,7 @@ Read this when choosing a `setup` mutation.
 | Permanently delete confirmed, unchanged, unused model files | `delete_local_model` |
 | TUI system shell | `set_system_shell` |
 | Automatic updates | `set_auto_update` |
+| Worktree defaults: new tasks on the current branch or a new worktree, branch prefix, large-repository warning size, automatic cleanup | `set_worktree_settings` |
 | Remove stored provider authentication (one OAuth account at a time) | `forget_provider_auth` |
 | Select, rename, reorder, or auto-switch OAuth accounts, or allow paid credits | `set_provider_account` |
 | Developer options such as risk-gated OAuth providers | `set_developer_option` |
@@ -85,7 +86,9 @@ Read this when choosing a `setup` mutation.
 Inspect `status model`, `status agents`, `status websearch`, or `status
 workflow` before changing the corresponding domain.
 
-- Main and agent routes also accept `modelParameters` and `contextPercent`; agent routes accept `disabled`.
+- Main and agent routes also accept `modelParameters`, `contextPercent`, and
+  `contextTokens` (an exact window in tokens that overrides `contextPercent`);
+  agent routes accept `disabled`.
   Use the model catalog for actual available options, not remembered model ids.
 - A Web Search route must support native web search; tool exposure is changed
   separately.

package/src/defaults/skills/visualize/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: visualize
+description: Show mockups, design options, diagrams, and finished artifacts beside the chat with the visualize tool.
+when_to_use: 'Mockups before UI work, design options, visual explanations, or showing a produced artifact; not production code alone.'
+metadata:
+  requires: visualize
+dependencies:
+  tools:
+    - type: tool
+      value: visualize
+---
+
+# Visualize (visualize tool)
+
+The side panel is where the user sees the work instead of reading about it.
+This file owns when to draw, how a mockup is built and iterated, and how results
+are shown. The schema owns action fields. `references/craft.md` owns the design
+bar every mockup is held to; read it before the first mockup of a session.
+
+## 1. Which job
+**Hard rule — seeing beats reading, or it is not this skill**: draw when the
+answer is a layout, a state, a flow, a spatial relation, or a look. Scope,
+tradeoffs, and wording decisions stay in chat even when the topic is UI.
+- *Show* — any artifact you produced or changed (HTML, deck, document, sheet,
+  PDF, image, video, a local dev page): `open` it once when it is ready. Edits
+  reload the tab by themselves; never reopen to refresh.
+- *Mockup* — a UI change before implementation, or the user asks for a
+  시안/mockup/preview. §2.
+- *Options* — the direction is genuinely open (the user is unsure, or two
+  readings of the request lead to different layouts). §3.
+- *Explain* — a flow, state machine, architecture, or data path the user needs
+  to grasp: one HTML diagram page, no option machinery.
+**Hard rule — not this tool**: authoring Office files, images, or video belongs
+to their own skills; this skill only shows their output. Clicking, typing, and
+testing a page belong to `browser`.
+
+## 2. Mockup loop
+1. **Ground in the real product.** Read the files that define the touched
+   surface — tokens, theme, the component and its neighbours — before drawing.
+   For an existing app screen, prefer the real screen (a capture of the running
+   app) with only the changed parts drawn over it; invented chrome hides what
+   actually changes. Done when you can name the exact component and values the
+   change touches.
+2. **Split the change into states.** Every state the user will meet gets its
+   own labelled frame: A default, B the interaction, C the result, D failure or
+   empty where they exist. One frame per state, captioned with what changed and
+   why in one sentence.
+3. **Write** `design/mockups/<topic>/index.html` (self-contained: inline CSS
+   and JS, no network). Sample data is realistic and marked as sample once in
+   the lead line; never fake metrics or filler sections.
+4. **Show**: `open` the page, then `annotate` each changed element with a short
+   label. Marks live on the panel, not in the file.
+5. **Look before you report.** Run `visualize check` on the tab and fix every
+   reported page problem (uncaught errors, CSP violations, console errors,
+   missing assets, blocked network requests: the page must be self-contained)
+   in the file, then `check` again until it reports none; a
+   "Page problems" section on any `open`, `annotate`, or `capture` result counts
+   the same. Then run `visualize inspect` on the tab: once at the panel's
+   width and, when the design is responsive, again with `viewport`
+   `{width: 375, height: 812}`; fix every finding it lists (overflow, clipped
+   text, tiny or overlapping targets, low contrast, missing alt or labels) in
+   the file before reporting. Then `capture` the tab (or read it through
+   `browser`) and check it against `references/craft.md` §5; fix what fails
+   before the user sees the report.
+6. **Report** in chat: path, the states shown, what to confirm, and the open
+   questions. Then stop — implementation waits for approval.
+7. **Iterate in place.** Feedback edits the same file; the tab reloads and the
+   panel keeps each saved state as a version (v1…vN) the user can step back
+   to, compare side by side, or restore, so never copy the file to keep an
+   old version. The user can also point at the page: their message then carries a
+   `<visualize_feedback>` block of numbered pins (`pin N` = the "📌 N" they
+   saw), each with the note, tab and project-relative file, and for an HTML
+   element its selector, label, trimmed HTML, key styles and box (a PDF or
+   image pin gives a region instead), plus the crop image "visualize pin N"
+   when there is one. Answer pin by pin by number and act on the element
+   the selector names; secret values arrive as `[redacted]`, so never restore
+   them from the crop or guess them.
+8. **After approval**: implement from the approved mockup; its values are the
+   spec. When the work needs a record, `export` the approved tab to PNG or PDF
+   beside the page (`export` with `format` and a project-relative `output`,
+   e.g. `design/mockups/login/login-approved.png`; `version` for a kept
+   version). A single HTML page renders whole in a hidden window, so the tab need
+   not be on screen; the result lists the written path, size, and any page
+   problems. Remove any temporary data or records you created to stage
+   the mockup, and say so.
+
+## 3. Options
+**Default — one strong mockup.** Options only when the direction is open.
+**Hard rule — options differ in stance, not in pixels**: pick one axis that
+matters for this decision (density, layout model, emphasis, interaction model)
+and pull the 2–3 options apart on it. Two options that differ by accent colour
+or radius are one option.
+- Name each by its stance ("1 · one menu", "2 · inline chips") and give its
+  cost in one line.
+- `open` 2–3 targets in one call to show them side by side.
+- Make the options pickable: put `data-choice="<id>"` on each option's root
+  (and `data-choice-group="<decision>"` when one page asks more than one
+  question; ungrouped choices form one group). A click selects one per group
+  and adds `data-choice-selected` to it; the panel's default outline uses
+  `:where()`, so style `[data-choice][data-choice-selected]` to match the
+  mockup. `data-choice-label` names it when its text does not. Picks reach
+  you with the user's next message under `choices:` in the
+  `<visualize_feedback>` block as tab, file, group, choice id and label.
+- When the user picks, consolidate into one mockup and close the others; a
+  pile of options is not a result.
+
+## 4. Showing results
+- Open a result once, when it is ready to look at, not at every intermediate
+  write. Long multi-step work shows the first reviewable state, then lets
+  reloads carry the rest.
+- Decks and documents: the panel shows the converted pages; still run the
+  owning skill's own render review — the panel is for the user, not your QC.
+- Close tabs that no longer match the conversation (a resolved choice, a
+  replaced draft) so the user is never looking at stale work.
+- A web URL is opened alone, never mixed with files; marking, capturing, or
+  closing a web page belongs to `browser`.
+- `annotate` and `capture` need the tab on screen (`export` of an HTML page does not). When they report the panel
+  is hidden, tell the user to open it rather than retrying.
+- When `visualize` is unavailable, give the file path; never start your own
+  server or pretend it was shown.
+
+### Inline content or a file
+- **Inline** (`open` with `input.content` — `mermaid`, `svg`, `chart` (an
+  ECharts option as JSON), `html`, `markdown`): diagrams, charts, quick
+  sketches and notes you will not edit again. No file is written. `mermaid`,
+  `svg` and `markdown` are static, sanitized output (no scripts). `chart` is
+  interactive (tooltips, zoom) and `html` runs its scripts, as in-memory pages
+  held to the same rules as an HTML file: outside network is blocked, so an
+  `html` sketch must be self-contained, and its page problems come back in the
+  result. Re-opening with the same `title` adds a version.
+- **File** (`targets`): a real mockup that needs iteration, scripts, assets,
+  versioning on disk, annotate/Comment feedback, or a deliverable the user keeps.
+- A render error comes back as a page problem (Mermaid parse error, bad chart
+  JSON): fix the source and open again; never report it as shown.
+
+### Tweaks
+Offer tweaks when the open decision is a value, not a layout: colour, density,
+spacing, type scale, radius. The page declares them in
+`<script type="application/json" id="mx-tweaks">` (HTML files and inline
+`html`/`chart`): `[{"id":"accent","label":"Accent","type":"color","var":"--accent","default":"#3b82f6"}]`.
+Types: `color` (hex/rgb), `range` (`min`,`max`,`step`,`unit`),
+`select` (`options`), `toggle`; each sets a `--css-var` or a
+`data-*` attribute on the root, which your CSS reads. Keep it to 6 or fewer
+meaningful controls (16 is the hard cap) and give every one a real default.
+The panel adds a Tweaks button; when the user sends their values you get them
+under `tweaks:` in `<visualize_feedback>` (`accent (--accent): #2f6fed (was
+#3b82f6)`): bake them into the file as the new defaults — both the CSS value
+and the control's `default`. A malformed block is a `tweaks: <reason>` page
+problem.
+
+## 5. Reporting
+Short: what is on screen, the path, the decision you need. Do not narrate the
+HTML. Uncertain or unverified rendering is stated, not glossed.
+The panel and the chat card already show the content: never repeat its source
+(Mermaid text, chart JSON, SVG, HTML) or re-render its data as a chat table or
+text chart. Name the tab and give one or two lines on what it shows or what to
+look at.

package/src/defaults/skills/visualize/references/craft.md

@@ -0,0 +1,88 @@
+# Craft bar for mockups and visual pages
+
+The bar is "a designer on this product drew it", not "a page was generated".
+Most generated-looking design is wrong composition, not wrong colour; fix the
+cause in the order below.
+
+## 1. Source before taste
+- An existing product wins over every rule here. Lift its real tokens,
+  spacing, radii, type, copy tone, and density from source files; do not
+  approximate from memory or a screenshot when the code is readable.
+- A new surface with no system: define a small one first (4–6 named colours,
+  one or two type families with roles, a spacing step, one radius scale) and
+  write it as CSS variables at the top of the page.
+- A brief's explicit direction wins, including when it asks for a look this
+  file warns against.
+
+## 2. Name the surface, then compose
+Before any colour or component, decide in one line what the user does here;
+the composition follows from it:
+
+| Surface | User is… | Composition carries |
+|---|---|---|
+| Watch | following changing state | density, glanceable hierarchy, no marketing framing |
+| Act | working through items | selection, row actions, clear current item |
+| Compare | weighing options | aligned columns, equal structure, one differentiator |
+| Set up | configuring | grouped fields, save/validation states, little decoration |
+| Persuade / teach | being convinced or taught | one idea per section; the only place a hero belongs |
+| Browse | exploring a space | filters, results, peek/zoom |
+| Drive / inspect | commanding or drilling into one object | keyboard paths, focus, detail panes |
+
+A screen spanning two picks a primary one; never average them.
+
+## 3. Hierarchy with type and space first
+- Scale, weight, and spacing carry hierarchy before boxes, borders, icons, or
+  colour. Add a container only when it groups something the user acts on.
+- Line length under ~80 characters; numbers in tables tabular and aligned.
+- Structural marks (numbers, dividers, labels) only when they encode real
+  information — numbered steps only for a real sequence.
+- One memorable element per page; everything around it stays quiet.
+
+## 4. Words are interface
+- Name things by what the user understands, not how the system is built.
+- Buttons say what happens ("Save changes"); the same action keeps the same
+  name through the flow ("Publish" → "Published").
+- Errors say what happened and what to do, without apology. Empty states
+  invite the next action.
+- Sentence case, plain verbs, no filler or invented claims. Draft copy is
+  marked as draft.
+
+## 5. Self-review before showing
+Look at the capture, list which of these fire, then repair by cause:
+
+Composition (re-layout; recolouring will not fix these):
+1. Wrong surface — e.g. a hero on a dashboard.
+2. Everything centred because no layout was chosen.
+3. Equal-weight tile grids (icon + heading + sentence ×3) where one thing
+   should lead.
+
+Decoration (remove; replace with scale, weight, or spacing):
+4. Coloured side rails on cards.
+5. Blur or glass with no elevation system behind it.
+6. Oversized stat numbers filling space meant for content.
+7. A rounded icon above every heading; icons that do not aid scanning.
+8. Identical cards, one radius and one soft shadow on everything.
+
+Defaults (recolour / re-typeset only if the brief left them free):
+9. Indigo/violet accent or glossy gradient chosen by habit.
+10. Default font used without a reason; ALL-CAPS eyebrow labels over every
+    heading; one word accented in a headline; "→" on every link.
+
+Re-check after repairing. Do not show while 1–3 still fire.
+
+## 6. Quality floor (always, without announcing it)
+`visualize inspect` reports most floor failures (overflow, clipped text,
+small or overlapping targets, low contrast, missing alt or labels); a page is
+not shown while it lists any.
+- Visible keyboard focus, real hover and disabled states where shown.
+- Readable contrast for text and controls; hit targets ≥ 44px on touch frames.
+- Motion only when it shows what changed; respect `prefers-reduced-motion`.
+- Fits the panel width without horizontal scroll; frames wider than the panel
+  scale down rather than clip.
+- Self-contained: no CDN, web font, API or other network request. The panel
+  blocks outside network unless the user allows it (a blocked request is a
+  `blocked-network` page problem), so inline or bundle every asset in the
+  project. No fake data passed off as real, or stock imagery.
+- A value the user may want to tune (accent, density, spacing) is a CSS variable
+  on the root plus a control in `<script type="application/json" id="mx-tweaks">
+  [{"id":"accent","type":"color","var":"--accent","default":"#3b82f6"}]`.

package/src/headless-command.mjs

@@ -1,5 +1,12 @@
+import { worktreeNameError } from './runtime/shared/worktrees/contract.mjs';
+
 const VALUE_OPTIONS = new Set(['--provider', '--model', '--effort', '--workflow']);
+// `--worktree [name]` takes an optional value; `--worktree=<name>` is the
+// unambiguous spelling.
+const WORKTREE_OPTION = '--worktree';
+const NO_WORKTREE_OPTION = '--no-worktree';
 const FLAG_OPTIONS = new Set([
+  NO_WORKTREE_OPTION,
   '--readonly',
   '--help',
   '-h',
@@ -12,7 +19,7 @@ const FLAG_OPTIONS = new Set([
   '--memory',
   '--json',
 ]);
-const EXEC_UNSUPPORTED_FLAGS = new Set(['--readonly', '--remote', '--onboarding', '--memory']);
+const EXEC_UNSUPPORTED_FLAGS = new Set(['--readonly', '--remote', '--onboarding', '--memory', NO_WORKTREE_OPTION]);
 const HEADLESS_WORKFLOW_ERROR = 'option --workflow is not supported for mixdog exec';
 
 function roleKey(value) {
@@ -22,6 +29,16 @@ function roleKey(value) {
     .replace(/[\s_]+/g, '-');
 }
 
+const isWorktreeOption = (arg) => arg === WORKTREE_OPTION || arg.startsWith(`${WORKTREE_OPTION}=`);
+
+/** The token after a bare `--worktree` is its name unless it is an option or the exec verb. */
+function worktreeNameToken(value) {
+  if (value === undefined || value === null) return null;
+  const text = String(value);
+  if (!text || text.startsWith('-') || roleKey(text) === 'exec') return null;
+  return text;
+}
+
 function argvIndicatesExec(argv) {
   for (let index = 0; index < argv.length; index += 1) {
     const arg = String(argv[index] ?? '');
@@ -29,6 +46,11 @@ function argvIndicatesExec(argv) {
       index += 1;
       continue;
     }
+    if (arg === WORKTREE_OPTION) {
+      if (worktreeNameToken(argv[index + 1]) !== null) index += 1;
+      continue;
+    }
+    if (isWorktreeOption(arg)) continue;
     if (arg === '--') continue;
     if (FLAG_OPTIONS.has(arg) || arg.startsWith('-')) continue;
     return roleKey(arg) === 'exec';
@@ -39,9 +61,23 @@ function argvIndicatesExec(argv) {
 function parseTokens(argv, { strictValues = true } = {}) {
   const positional = [];
   const values = {};
+  let worktree;
   const allowHeadlessIntent = strictValues && !argv.includes('--react');
   for (let index = 0; index < argv.length; index += 1) {
     const arg = String(argv[index] ?? '');
+    if (isWorktreeOption(arg)) {
+      let name = arg === WORKTREE_OPTION ? null : arg.slice(WORKTREE_OPTION.length + 1);
+      if (name === null) {
+        name = worktreeNameToken(argv[index + 1]);
+        if (name !== null) index += 1;
+      }
+      const nameError = name === null ? null : worktreeNameError(name);
+      if (nameError && strictValues) {
+        return { error: `option --worktree name ${JSON.stringify(name)} is invalid: ${nameError}` };
+      }
+      worktree = { mode: 'worktree', name: nameError ? null : name };
+      continue;
+    }
     if (VALUE_OPTIONS.has(arg)) {
       const value = argv[index + 1];
       if (value === undefined || value === '' || String(value).startsWith('-')) {
@@ -87,7 +123,19 @@ function parseTokens(argv, { strictValues = true } = {}) {
     }
     positional.push(arg);
   }
-  return { positional, values };
+  return { positional, values, worktree };
+}
+
+/**
+ * Session creation intent from `--worktree [name]` / `--no-worktree`:
+ * undefined follows the worktree settings default.
+ * @returns {{ worktree?: { mode: 'worktree', name: string|null } | { mode: 'branch' } } | { error: string }}
+ */
+function worktreeIntent(argv, parsed) {
+  const disabled = argv.includes(NO_WORKTREE_OPTION);
+  if (disabled && parsed.worktree) return { error: 'options --worktree and --no-worktree are mutually exclusive' };
+  if (disabled) return { worktree: { mode: 'branch' } };
+  return parsed.worktree ? { worktree: parsed.worktree } : {};
 }
 
 function execFromPositional(positional) {
@@ -103,7 +151,10 @@ export function classifyCliInvocation(argv = []) {
   const hasPlain = argv.includes('--plain');
   const parsed = parseTokens(argv, { strictValues: !hasHelp && !hasPlain });
   if (parsed.error) return { kind: 'error', ...parsed };
+  const intent = worktreeIntent(argv, parsed);
+  if (intent.error && !hasHelp && !hasPlain) return { kind: 'error', error: intent.error };
   const options = {
+    ...(intent.worktree ? { worktree: intent.worktree } : {}),
     provider: parsed.values['--provider'],
     model: parsed.values['--model'],
     effort: parsed.values['--effort'],
@@ -129,7 +180,9 @@ export function classifyCliInvocation(argv = []) {
         skipHostPrelude: true,
       };
     }
-    const unsupported = [...EXEC_UNSUPPORTED_FLAGS].find((flag) => argv.includes(flag));
+    const unsupported =
+      [...EXEC_UNSUPPORTED_FLAGS].find((flag) => argv.includes(flag)) ||
+      (parsed.worktree ? WORKTREE_OPTION : undefined);
     if (unsupported) {
       return {
         kind: 'error',

package/src/headless-exec.mjs

@@ -75,6 +75,7 @@ export async function runHeadlessExec({
   memoryRuntimeCleanup = stopStandaloneMemoryRuntimesForProcess,
   daemonRuntimeCleanup = shutdownDaemonForRuntimeRoot,
   usageLedgerCleanup = closeUsageLedgers,
+  sessionStoreDrain = drainHeadlessSessionStore,
   hasActiveTasks = hasActiveBackgroundTasks,
   installSignalCleanupFn = installProcessSignalCleanup,
 } = {}) {
@@ -122,6 +123,7 @@ export async function runHeadlessExec({
     memoryRuntimeCleanup,
     daemonRuntimeCleanup,
     usageLedgerCleanup,
+    sessionStoreDrain,
     hasActiveTasks,
     installSignalCleanupFn,
   });
@@ -155,6 +157,7 @@ async function executeHeadlessPrompt(
     memoryRuntimeCleanup,
     daemonRuntimeCleanup,
     usageLedgerCleanup,
+    sessionStoreDrain,
     hasActiveTasks,
     installSignalCleanupFn,
   }
@@ -172,6 +175,7 @@ async function executeHeadlessPrompt(
     writeErr,
     hasActiveTasks,
     usageLedgerCleanup,
+    sessionStoreDrain,
     daemonRuntimeCleanup,
     memoryRuntimeCleanup,
   });
@@ -266,7 +270,7 @@ function taskScopeFor(session) {
 // pristine root.
 function headlessCleanup(
   run,
-  { writeErr, hasActiveTasks, usageLedgerCleanup, daemonRuntimeCleanup, memoryRuntimeCleanup }
+  { writeErr, hasActiveTasks, usageLedgerCleanup, sessionStoreDrain, daemonRuntimeCleanup, memoryRuntimeCleanup }
 ) {
   let cleanupPromise = null;
   const shutdown = async (reason) => {
@@ -289,6 +293,13 @@ function headlessCleanup(
         await drainAgentTrace();
       }
     });
+    // The session store's process-exit hook flushes any save still pending
+    // at exit to the data dir resolved AT THAT MOMENT — by then the boundary
+    // has restored the host environment, so a late write would land in the
+    // host's session catalog. Flush while the pristine data dir is current.
+    await attemptShutdownStep(errors, async () => {
+      if (boundary) await sessionStoreDrain();
+    });
     // The usage ledger lives inside the pristine root. Its open SQLite
     // handle blocks the root removal below on Windows (EBUSY) for the whole
     // rmSync retry budget, so release it once the last usage row is in.
@@ -316,6 +327,11 @@ function headlessCleanup(
   };
 }
 
+async function drainHeadlessSessionStore() {
+  const { drainSessionStore } = await import('./runtime/agent/orchestrator/session/store.mjs');
+  drainSessionStore();
+}
+
 // Runs one shutdown step, collecting its failure so the remaining steps still
 // run; true when the step succeeded.
 async function attemptShutdownStep(errors, step) {

package/src/headless-role.mjs

@@ -140,8 +140,8 @@ export async function runHeadlessRole({
 } = {}) {
   const cleanAgent = clean(agent);
   const cleanMessage = clean(message);
-  // Classic headless surface: web search and memory tools start OFF
-  // and opt back in per run (--web-search / --memory). An explicit
+  // Web search and memory start OFF. This call can pass webSearch or memory;
+  // exec accepts --web-search and rejects --memory. An explicit
   // MIXDOG_FEATURE_* value from the caller environment always wins.
   for (const [key, enabled] of [
     ['MIXDOG_FEATURE_WEB_SEARCH', webSearch],

package/src/help.mjs

@@ -17,6 +17,8 @@ const HELP_LINES = [
   '  --web-search        enable web search and page retrieval for headless exec',
   '  --json              emit headless exec events as JSONL',
   '  --workflow <name>   start with the given workflow active',
+  '  --worktree [name]   run this session in a new git worktree (optionally named)',
+  '  --no-worktree       run this session on the current branch in the project folder',
   '  --readonly          read-only tool surface',
   '  --remote            enable remote/channel mode for this session',
   '  --onboarding        re-run the first-run setup wizard',