dsh-wayfinder-ui

What it does

A tracker-agnostic Wayfinder runner plugin for DeepSeek Harness (DSH): every new session learns a three-verb registration contract, maps live in a per-workspace registry file at .wayfinder-runner/state.json (committed), and the UI polls /dsh-wayfinder/state.json.

When to reach for it

You chart Wayfinder maps for DSH work and want every ready task picked up by its own top-level session while the dependency map tracks progress live — regardless of where the tasks are tracked (dex, Jira, GitHub issues, markdown files).

Prerequisites

• Node.js ≥22 (see engines in package.json)
• DSH with the web profile (~/.dsh/profiles/web/)
• pnpm or npm for local development

Install

# 1. Clone anywhere
git clone https://github.com/andrepontesmelo/dsh-wayfinder-ui.git
# 2. Symlink into the web profile
ln -s /path/to/dsh-wayfinder-ui ~/.dsh/profiles/web/node_modules/dsh-wayfinder-ui

Append the plugin row to ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: wayfinder
      name: 'dsh-wayfinder-ui'

Spawned sessions inherit the spawning session's route (provider/model); optional provider/model arguments on wayfinder_spawn_session override that inheritance per call.

They join the spawning session's workspace as well; when the caller is Ungrouped — or the wayfinder root lies outside the caller's own workspace directory, which upstream attach validation rejects — the spawned session stays Ungrouped instead of being forcibly regrouped.

Restart the GUI. The model tools and the map panel both load on startup.

npm: npm install dsh-wayfinder-ui is planned after manual validation — GitHub is the install source until then.

It's working if

• A fresh session receives the three-verb contract on startup, and Settings → Wayfinder lists the toggles.
• wayfinder_map_create writes .wayfinder-runner/state.json and the right rail renders your map's task rows.
• An approved spawn opens one top-level session per ready task, and a worker's wayfinder_task_resolve flips its row to done.

Tools

All seven are model-callable once the plugin is installed.

• wayfinder_snippet — prints the protocol: propose ready wayfinder tasks to the human, ask for explicit approval, then call wayfinder_spawn_session exactly once. Never spawn without approval. It also documents the seed-message format and the route-inheritance rule.
• wayfinder_spawn_session — spawns one top-level DSH session per ready task, in parallel. Tasks come from the registry frontier: omit tasks to spawn every ready task (derived status todo; done and blocked-by-undone rows are skipped). Each seed carries a Task locator line pointing at where the task's work lives, so workers find their real tickets wherever they are tracked — dex, Jira, GitHub issues, markdown files. Each spawned session joins the spawning session's workspace and inherits its route; pass optional provider/model to override per call.
• wayfinder_map_create — charts a new map into the registry: validates tasks: [{id, title, type?, locator, blockedBy?}], persists it at <root>/.wayfinder-runner/state.json, and makes it the selected open map.
• wayfinder_task_resolve — marks one task done because a worker finished it (the worker-report path), stamping the reporting session onto the row.
• wayfinder_task_set_status — manual override of one task's status (todo|done|running|waiting|blocked). Prefer wayfinder_task_resolve for worker completion reports.
• wayfinder_map_sync — create-or-replace a map by name with a complete task list; also registered as the /wayfinder-map-sync recovery hatch.
• wayfinder_grilling_start — report that a grilling task's session has begun grilling a batch and awaits the user. Stamps grillingSince on the row, which lights a flame in the panels (right rail + in-session card); wayfinder_task_resolve clears it. Grilling-typed spawns carry the instruction in their seed.

How it works

1. Chart — wayfinder_map_create validates the task list and persists the map as the selected open map of the workspace registry.
2. Spawn — each approved task gets a top-level DSH session seeded with /wayfinder work on task (TASK_ID) of map (MAP_NAME) (the leading /wayfinder gesture makes the harness inject the skill content, exactly as if the human typed the slash command) plus its Task locator line.
3. Report — workers finish by calling wayfinder_task_resolve, which marks their task done and links the reporting session.
4. Derive — done comes from reports/manual overrides, blocked from blockedBy edges, and running/waiting are computed live from the spawned sessions (running agent; idle agent whose newest model-visible event is an assistant message).
5. Restart — the plugin reloads the state file: selectedMapId wins (falling back to the newest open map), and sessions re-associate with their rows by matching the seeded message.

Surfaces

• In-session card — the collapsible To-dos-style card above the composer renders only in the session that charted the map: the payload carries createdBySessionId, and the dock compares it against its own session. A map without a stamped owner (hand-written registry) shows no card anywhere; call wayfinder_map_sync once from your session to claim it.
• Right rail and ambient sidebar badges stay workspace-wide on purpose: mission control should be visible from every session. Both remain individually togglable in Settings → Wayfinder.
• Session links — task rows on the rail (and on an expanded card) carry an ↗ link when a session is spawned for that row; clicking opens that session, exactly like clicking its sidebar row.
• Grilling flames — one 🔥 per live grilling batch: a grilling-typed session calls wayfinder_grilling_start when it starts grilling and waits for you; the rail and card show a flame pill (N grilling) plus a per-row flame until the task resolves.

Development

pnpm install
npm test        # node --test

Known limitations

• Web profile only: the card, right rail, and sidebar badges live in the DSH GUI.
• Spawns target the registry's selected open map (selectedMapId, falling back to the newest open map).

License

MIT © 2026 Andre Melo