@maci0/dsh-loop 0.10.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel W. Wysocki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# dsh-loop
+
+Repeat a command across agent turns in DeepSeek Harness. `/loop` queues a
+command as the agent's next turn and queues it again after each completed
+turn, for a fixed number of rounds or until you stop it.
+
+## What you get
+
+```
+/loop 10 /perf-review               # run /perf-review for 10 rounds
+/loop 10 /perf-review && /cordis-review  # run both commands every round
+/loop 10 continue                   # send "continue" for 10 rounds
+/loop 0 continue                    # loop forever (0 = infinite)
+/loop pause                         # hold the round; resume picks it back up
+/loop resume                        # continue a paused loop
+/loop stop                          # end the running loop
+/loop status                        # what is running, and how far along
+```
+
+Files attached to a `/loop <rounds> <command>` go out with round 1. `pause`,
+`resume`, `stop`, and `status` take no attachments: they answer an error and
+the composer keeps the files.
+
+The command can span multiple lines; each round preserves its formatting.
+
+In the Web client, a pill above the composer shows the running loop with
+Pause, Resume, and Stop buttons.
+
+## Install
+
+> **Install it as a bundle.** `dsh plugin add …` mounts the row from the
+> package's own patch layer, which is what the settings editor can write to. A
+> row added with `--patch` is an overlay: it disappears at the next start.
+
+```sh
+dsh plugin --profile web add @maci0/dsh-loop@0.10.1
+```
+
+This installs the public npm package; no GitHub token or `~/.secrets` setup is needed.
+The version is pinned. To upgrade, run the same command with a newer version,
+then restart `dsh web` (bundle layers compose at boot).
+
+The bundled `cordis.patch.yml` inserts the `loop` row automatically.
+
+## How it works
+
+`/loop <rounds> <command>` queues the command as the agent's next turn (round
+1). When the turn that round opened completes, the plugin queues the next
+round until the budget is spent. `rounds = 0` never spends; `/loop stop`
+cancels at any time, and `/loop status` answers whether one is running or
+paused, and at which round. The pill shows the same state, but only the Web
+client has a pill. Loops are per-session.
+
+Only the turn a round's own queued message opened moves the loop. A turn
+already running when `/loop` was typed, or one you open between rounds,
+leaves the round where it is. A round turn that ends any way other than
+`completed` (aborted, error, blocked, max-tokens, or interrupted by a
+restart) pauses the loop at that round; `/loop resume` runs the same round
+again.
+
+A round is queued once the agent reaches quiescence (`Agent.whenIdle()`),
+never from inside the `turn/end` publication: `followup()` appends, a session
+refuses an append that reenters the event it is publishing, and a wake
+delivered before the retiring turn settles opens no turn.
+
+### The pill
+
+While a loop is active or paused, a pill (`⟳ command run/rounds` + Pause /
+Resume + Stop) docks in the same `conversation.input.dock` strip as the goal
+bar, ordered right beside it. State path: a `sessionProjections` unit (key
+`loop`) folds events the harness already understands (the plugin's own
+`command/run` and `command/done` rows, and the `user/message` relay lines the
+driver queues each round), and the client half reads the projected view via
+`useProjection('loop')`: push-based, no polling, correct across reloads. A
+verb moves the pill only once its `command/done` settles as `success`. The
+driver appends no custom event type: an unknown non-ignorable type makes the
+persistence read path refuse the whole session. The buttons submit the
+host-side `/loop pause | resume | stop` commands (no model turn). A verb that
+fails replaces the label with "Stop failed" (or Pause, Resume), the error
+message as its tooltip, until the next action or projection change.
+
+### Restarts
+
+The round driver is process memory; the folded log is durable. After a
+restart the verbs re-adopt an `active` or `paused` fold from the projection
+registry, with the round turn in flight and the round a pause or interruption
+holds, so `/loop stop` clears a pill the fresh process never started, the pill
+can never strand, and `/loop resume` runs the held round. A round turn cut off
+by the restart is closed as `interrupted` in the log, which pauses the loop. A
+stopped or spent fold stays dead and is never re-adopted.
+Queued relays carry the original loop invocation id, so a relay from a stopped
+or replaced loop cannot reactivate its pill or overwrite the newer loop.
+
+## Limits
+
+- A command that names a skill (`/perf-review`) is queued as a user message
+  containing that command; the agent invokes the skill on its turn.
+- No round cap on infinite loops: it runs until `/loop stop`. Watch quota.
+- A finite budget is a whole number up to 9007199254740991; larger values are
+  rejected.
+
+## Development
+
+dsh loads plugins on Node `^22.19.0 || >=24.0.0`; development and tests run on
+bun.
+
+```sh
+bun install --frozen-lockfile
+bun test
+```
+
+For local development, `dsh plugin --profile <name> add <path-to-checkout>`.
+
+## Licence
+
+MIT, see [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# Bundle layer: applied when a profile lists this bundle in dsh.profile.bundles
+# (dsh plugin add does that from dsh.bundle). That list is frozen at boot.
+# Do not also paste this row into the profile's cordis.patch.yml: insert does
+# not dedupe ids, two rows would register the plugin twice.
+- insert:
+    - id: loop
+      name: '@maci0/dsh-loop'

package/icon.svg

@@ -0,0 +1,4 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path d="M18 8.5a9.5 9.5 0 1 1-6.8 2.8" stroke="#145AF3" stroke-width="2.4" stroke-linecap="round"/>
+  <path d="M11.2 6.2v6.2h6.2" stroke="#145AF3" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/index.js

@@ -0,0 +1,420 @@
+/**
+ * dsh-loop: repeat a command on a cadence of agent turns.
+ *
+ * `/loop <rounds> <command>` queues the command as the agent's next turn and,
+ * after each completed turn, queues the next round until the budget is spent.
+ * rounds = 0 means loop forever; `/loop stop` ends the loop early.
+ *
+ * Examples:
+ *   /loop 10 /perf-review
+ *   /loop 10 /perf-review && /cordis-review
+ *   /loop 10 continue
+ *   /loop 0 continue
+ *   /loop pause
+ *   /loop resume
+ *   /loop stop
+ *
+ * Install with `dsh plugin --profile <name> add @maci0/dsh-loop@<version>`.
+ * For local development, `dsh plugin --profile <name> add <path-to-checkout>`.
+ */
+import { z } from 'zod'
+import { createUserMessage } from '@deepseek-ai/dsh-llm/message'
+
+export const name = 'loop'
+// `agents` resolves the session's agent on turn/end (round driver); the
+// projection registry serves the pill's live loop state to the client half.
+export const inject = ['commands', 'agents']
+
+/**
+ * Parse `/loop` arguments: `<rounds> <command>`, or `pause` / `resume` /
+ * `stop` / `status` (`list` is an alias). The command is free text passed
+ * verbatim to the agent each round, so slash-command chains such as
+ * `/perf-review && /cordis-review` replay as written. There is one deliberate
+ * restriction: a nested `/loop stop` would end the loop from inside its own
+ * replay and leave the loop with no way to stop, so it is rejected before the
+ * loop starts.
+ * @param {string} input - raw text after `/loop`.
+ * @returns {{ kind: 'pause' } | { kind: 'resume' } | { kind: 'stop' } | { kind: 'status' } |
+ *            { kind: 'error', text: string } |
+ *            { kind: 'loop', rounds: number, command: string }}
+ *   `rounds` is the total round budget; 0 means infinite.
+ */
+export function parseArgs(input) {
+  const trimmed = input.trim()
+  const verb = trimmed.toLowerCase()
+  if (verb === 'stop') return { kind: 'stop' }
+  if (verb === 'pause') return { kind: 'pause' }
+  if (verb === 'resume') return { kind: 'resume' }
+  // A status verb exists because the pill is a Web surface: a session driven
+  // from a terminal has no other way to ask whether a loop is running.
+  if (verb === 'status' || verb === 'list') return { kind: 'status' }
+  const match = /^(\d+)\s+([\s\S]+)$/.exec(trimmed)
+  if (!match) {
+    return {
+      kind: 'error',
+      text: 'Usage: /loop <rounds> <command>, for example /loop 10 /perf-review, /loop 10 /perf-review && /cordis-review, /loop 0 continue (0 = forever). Or /loop pause | resume | stop | status.',
+    }
+  }
+  const command = match[2].trim()
+  if (/\/loop\s+stop\b/i.test(command)) {
+    return {
+      kind: 'error',
+      text: 'A nested /loop stop would end the loop from inside its own replay. Stop it from the composer instead.',
+    }
+  }
+  // The budget rides in the projection's integer schema and the round relay
+  // line, so it must stay an exact integer.
+  const rounds = Number(match[1])
+  if (!Number.isSafeInteger(rounds)) {
+    return { kind: 'error', text: `Rounds must be a whole number from 0 to ${Number.MAX_SAFE_INTEGER}.` }
+  }
+  return { kind: 'loop', rounds, command }
+}
+
+/** Human label for the budget. */
+export function budgetLabel(rounds) {
+  return rounds === 0 ? '∞ (stop with /loop stop)' : String(rounds)
+}
+
+/** The queued user message for one round. */
+export function roundMessage(command, run, rounds) {
+  return `[loop round ${run}/${budgetLabel(rounds)}]\n${command}`
+}
+
+// Projection: the /loop pill's live state.
+//
+// The pill folds only events the harness already understands (the loop's own
+// `command/run` and `command/done` rows, and the `user/message` relay lines
+// the driver queues each round), so the plugin never appends a custom event
+// type. A custom type would poison the log: the persistence read path refuses
+// any session containing an unknown non-ignorable type, and the envelope
+// marker cannot be attached through `Session.append`. Out-of-repo plugins
+// cannot extend the known-type catalog, so the durable fold reads only
+// canonical history.
+
+/**
+ * Parse one round relay line back into its loop fields. Returns `undefined`
+ * for any message the driver did not write.
+ */
+export function parseRoundLine(text) {
+  const match = /^\[loop round (\d+)\/(.+?)\]\n([\s\S]+)$/.exec(text)
+  if (!match) return undefined
+  const run = Number(match[1])
+  // The infinite budget reads by its leading glyph: the label after it is
+  // display text, and logs written by older releases must keep folding.
+  const budget = /^∞(?: .*)?$/.test(match[2]) ? 0 : Number(match[2])
+  const command = match[3].trim()
+  if (!Number.isSafeInteger(run) || run < 1 || !Number.isSafeInteger(budget) || budget < 0 || command === '') return undefined
+  return { run, rounds: budget, command }
+}
+
+/** True for a message the loop driver queued. */
+function isLoopRelay(event) {
+  return event.type === 'user/message'
+    && event.data?.source?.kind === 'loop'
+}
+
+/** The pill's client view: the running or paused loop, or null for none. */
+const loopViewSchema = z.object({
+  phase: z.enum(['active', 'paused']),
+  command: z.string().min(1),
+  rounds: z.number().int().nonnegative(),
+  run: z.number().int().positive(),
+}).nullable()
+
+/**
+ * Fold state: the view, the `/loop` invocation whose `command/run` row awaits
+ * its `command/done`, whether the turn a round's relay opened is still
+ * running (`inRound`), and the round a pause or an interruption holds back
+ * (`held`). The executor appends `command/run` before attachment admission
+ * and the handler, so a verb applies only once its paired `command/done`
+ * settles as `success`. `inRound` and `held` mirror the driver's memory, so a
+ * remount or restart adopts them.
+ */
+const loopStateSchema = z.object({
+  loop: loopViewSchema,
+  loopId: z.string().nullable(),
+  pending: z.object({ commandId: z.string(), args: z.string() }).nullable(),
+  inRound: z.boolean(),
+  held: z.number().int().positive().nullable(),
+})
+
+/** Apply one settled `/loop` invocation's arguments to the fold. */
+function settleVerb(state, args) {
+  const parsed = parseArgs(args)
+  const loop = state.loop
+  if (parsed.kind === 'loop') {
+    // Round 1's relay always lands after this row: the agent appends it only
+    // once its turn claims the inbox, past an await.
+    return { loop: { phase: 'active', command: parsed.command, rounds: parsed.rounds, run: 1 }, loopId: state.pending.commandId, pending: null, inRound: false, held: null }
+  }
+  if (parsed.kind === 'stop') return { loop: null, loopId: state.pending.commandId, pending: null, inRound: false, held: null }
+  if (loop === null) return { ...state, pending: null }
+  if (parsed.kind === 'pause' && loop.phase === 'active') {
+    // Paused between rounds, the driver holds the next round once its wait
+    // for quiescence ends; a relay that still lands replaces this guess.
+    const held = state.inRound ? state.held : loop.run + 1
+    return { ...state, loop: { ...loop, phase: 'paused' }, pending: null, held }
+  }
+  if (parsed.kind === 'resume' && loop.phase === 'paused') {
+    return { ...state, loop: { ...loop, phase: 'active' }, pending: null, held: null }
+  }
+  return { ...state, pending: null }
+}
+
+/**
+ * The projection unit: fold the loop's own settled invocations (start, pause,
+ * resume, stop; the definition records input, so `command/run` carries the
+ * verb verbatim in `args`), the claimed `user/message` relay lines (round
+ * counter advances), and the end of each turn a relay opened into the pill's
+ * client view. A turn no relay opened never moves the fold. Registered
+ * through `ctx.inject(['sessionProjections'], …)` so headless assemblies
+ * without the registry stay unaffected.
+ */
+export const loopProjection = {
+  key: 'loop',
+  stateSchema: loopStateSchema,
+  init: () => ({ loop: null, loopId: null, pending: null, inRound: false, held: null }),
+  apply: (state, event) => {
+    if (event.type === 'turn/end') {
+      if (!state.inRound) return state
+      const loop = state.loop
+      if (event.data?.reason?.kind !== 'completed') {
+        // An interrupted round pauses the loop and holds that same round.
+        return { ...state, inRound: false, loop: { ...loop, phase: 'paused' }, held: loop.run }
+      }
+      // The spent budget is the fold's terminal edge. The driver drops a spent
+      // loop with nothing appended (the round relay is the last canonical
+      // row), so this turn/end is the only signal that the pill must clear.
+      if (loop.rounds !== 0 && loop.run >= loop.rounds) return { ...state, inRound: false, loop: null, loopId: state.loopId ?? '', held: null }
+      return { ...state, inRound: false, held: loop.phase === 'paused' ? loop.run + 1 : null }
+    }
+    if (event.type === 'command/run' && event.data?.name === 'loop'
+      && typeof event.data.commandId === 'string' && typeof event.data.args === 'string') {
+      return { ...state, pending: { commandId: event.data.commandId, args: event.data.args } }
+    }
+    if (event.type === 'command/done') {
+      const pending = state.pending
+      if (pending === null || event.data?.commandId !== pending.commandId) return state
+      return event.data.kind === 'success' ? settleVerb(state, pending.args) : { ...state, pending: null }
+    }
+    if (!isLoopRelay(event)) return state
+    // A relay already in the inbox may land after stop or a replacement start.
+    if (state.loop === null && state.loopId !== null) return state
+    if (event.data.source.loopId !== undefined && event.data.source.loopId !== state.loopId) return state
+    const blocks = Array.isArray(event.data?.content) ? event.data.content : []
+    const text = blocks.filter((block) => block?.type === 'text').map((block) => block.text).join('')
+    const round = parseRoundLine(text)
+    if (!round) return state
+    // A relay queued before a pause still runs; the loop stays paused.
+    const phase = state.loop?.phase === 'paused' ? 'paused' : 'active'
+    return { ...state, inRound: true, held: null, loop: { phase, command: round.command, rounds: round.rounds, run: round.run } }
+  },
+  wire: {
+    viewSchema: loopViewSchema,
+    view: state => state.loop,
+  },
+  stateVersion: 6,
+}
+
+/**
+ * Queue one round as the agent's next turn. The relay's message id is how the
+ * driver recognizes the turn that round opened: only that turn's end moves
+ * the loop, never a turn the user or another plugin opened.
+ * @param {object} agent - the session's agent.
+ * @param {object} loop - the driven loop.
+ * @param {number} run - the round to queue.
+ * @param {readonly object[]} attachments - blocks to send with the round.
+ */
+function queueRound(agent, loop, run, attachments) {
+  const message = createUserMessage({
+    content: [...attachments, { type: 'text', text: roundMessage(loop.command, run, loop.rounds) }],
+    source: { kind: 'loop', form: 'relay', ...(loop.id === undefined ? {} : { loopId: loop.id }) },
+  })
+  loop.run = run
+  loop.relayId = message.id
+  loop.turnOpen = false
+  agent.followup(message)
+}
+
+/**
+ * Read the durable loop view for one session. The round driver's `loops` map
+ * is process memory and dies on restart; the session log and the projection
+ * unit folding it survive. Without this fallback, a restart leaves the pill
+ * showing an active loop the verbs cannot see: `/loop stop` answers "No loop
+ * is running" while the pill never clears.
+ */
+function readProjectedLoop(ctx, session) {
+  try {
+    const projected = ctx.get?.('sessionProjections')?.stateOf?.(session, 'loop')
+    return projected?.loop ? projected : undefined
+  } catch {
+    // A fold that cannot materialize (a gap in the log) leaves the verbs on
+    // the live map alone, the same answer as a host without the registry.
+    return undefined
+  }
+}
+
+/**
+ * The loop for one session: the live map entry, or the durable view adopted
+ * back into the map when the process forgot it (restart, remount), with the
+ * round turn in flight and the held round. A null view (stopped or spent)
+ * stays dead.
+ */
+function liveLoop(ctx, state, session) {
+  const loop = state.loops.get(session.id)
+  if (loop) return loop
+  const fold = readProjectedLoop(ctx, session)
+  if (!fold) return undefined
+  const adopted = {
+    id: fold.loopId ?? undefined,
+    command: fold.loop.command,
+    rounds: fold.loop.rounds,
+    run: fold.loop.run,
+    paused: fold.loop.phase === 'paused',
+    held: fold.held ?? undefined,
+    turnOpen: fold.inRound === true,
+  }
+  state.loops.set(session.id, adopted)
+  return adopted
+}
+
+function loopHandler(invocation, state, ctx) {
+  const parsed = parseArgs(invocation.rawInput)
+  if (parsed.kind === 'error') return { kind: 'error', text: parsed.text }
+
+  // Only a start sends attachments (with round 1). A verb opens no turn of its
+  // own, so it refuses them and the composer keeps the files, as the command
+  // contract asks of a handler that cannot use them.
+  if (parsed.kind !== 'loop' && invocation.attachments.length > 0) {
+    return { kind: 'error', text: `/loop ${parsed.kind} takes no attachments; send them with the command a loop repeats.` }
+  }
+
+  const sessionId = invocation.agent.session.id
+  if (parsed.kind === 'stop') {
+    const loop = liveLoop(ctx, state, invocation.agent.session)
+    if (!loop) return { kind: 'success', text: 'No loop is running.' }
+    state.loops.delete(sessionId)
+    return { kind: 'success', text: `Loop for "${loop.command}" stopped after ${loop.run} round(s).` }
+  }
+  if (parsed.kind === 'status') {
+    const loop = liveLoop(ctx, state, invocation.agent.session)
+    if (!loop) return { kind: 'success', text: 'No loop is running.' }
+    const state_ = loop.paused ? 'paused' : 'running'
+    return {
+      kind: 'success',
+      text: `Loop for "${loop.command}" is ${state_} at round ${loop.run} of ${budgetLabel(loop.rounds)}.`,
+    }
+  }
+  if (parsed.kind === 'pause') {
+    const loop = liveLoop(ctx, state, invocation.agent.session)
+    if (!loop) return { kind: 'success', text: 'No loop is running.' }
+    if (loop.paused) return { kind: 'success', text: `Loop for "${loop.command}" is already paused at round ${loop.run}.` }
+    loop.paused = true
+    return { kind: 'success', text: `Loop for "${loop.command}" paused at round ${loop.run}.` }
+  }
+  if (parsed.kind === 'resume') {
+    const loop = liveLoop(ctx, state, invocation.agent.session)
+    if (!loop) return { kind: 'success', text: 'No loop is running.' }
+    if (!loop.paused) return { kind: 'success', text: `Loop for "${loop.command}" is already running.` }
+    loop.paused = false
+    const text = `Loop for "${loop.command}" resumed at round ${loop.run}.`
+    // The round a paused or interrupted turn held back has to be queued here:
+    // pause and resume are plugin commands and open no turn, so nothing else
+    // would ever drive it.
+    const held = loop.held
+    loop.held = undefined
+    if (held !== undefined) queueRound(invocation.agent, loop, held, [])
+    return { kind: 'success', text }
+  }
+
+  const loop = { id: invocation.commandId, command: parsed.command, rounds: parsed.rounds, run: 1 }
+  state.loops.set(sessionId, loop)
+  queueRound(invocation.agent, loop, 1, invocation.attachments)
+  return {
+    kind: 'success',
+    text: `Loop started: "${parsed.command}" for ${budgetLabel(parsed.rounds)} round(s).`,
+  }
+}
+
+export function apply(ctx) {
+  // Per-instance driver state: module-level state would outlive an unload and
+  // leak across instances.
+  const state = { loops: new Map() }
+
+  // Serve the pill's live loop state when the projection registry is mounted.
+  ctx.inject?.(['sessionProjections'], (scope) => {
+    scope.sessionProjections.register(loopProjection)
+  })
+
+  ctx.effect(() => {
+    const disposers = []
+    disposers.push(ctx.commands.register({
+      definitionId: 'dsh-loop:loop',
+      name: 'loop',
+      description: '⟳ Repeat a command each turn: /loop <rounds> <command> (0 = forever), /loop pause | resume | stop | status',
+      input: { hint: '<rounds> <command> | pause | resume | stop | status', attachments: true },
+      handler: (inv) => loopHandler(inv, state, ctx),
+    }))
+    // After the turn a round opened completes, queue the next round until the
+    // budget spends. A turn the round did not open (one already running when
+    // /loop was typed, one the user opened between rounds) never moves the
+    // loop. A round turn that ends any other way (aborted, error, blocked,
+    // max-tokens, interrupted by a restart) pauses the loop and holds that same
+    // round for resume. A paused loop holds its next round: the completed turn
+    // settles with nothing queued, and resume picks up exactly where it left
+    // off. The pill follows the same rows, so the driver appends nothing.
+    const offTurn = ctx.on('session/event', (session, event) => {
+      const loop = state.loops.get(session.id)
+      if (!loop) return
+      if (event?.type === 'user/message') {
+        if (event.data?.source?.kind === 'loop' && event.data.id === loop.relayId) loop.turnOpen = true
+        return
+      }
+      if (event?.type !== 'turn/end' || !loop.turnOpen) return
+      loop.turnOpen = false
+      loop.relayId = undefined
+      if (event.data?.reason?.kind !== 'completed') {
+        loop.paused = true
+        loop.held = loop.run
+        return
+      }
+      if (loop.rounds !== 0 && loop.run >= loop.rounds) {
+        state.loops.delete(session.id)
+        return
+      }
+      // A paused loop holds its round rather than dropping it; `resume` queues
+      // it, because a turn/end is the only other driver and a plugin command
+      // starts no turn.
+      if (loop.paused) {
+        loop.held = loop.run + 1
+        return
+      }
+      const agent = ctx.agents.get(session.id)
+      if (!agent || agent.session !== session) return
+      const run = loop.run + 1
+      loop.run = run
+      // The round waits for quiescence: `followup` appends, and a session
+      // refuses an append that reenters the event being published, while a
+      // wake delivered before the retiring turn settles never opens a turn.
+      // A stop, pause, or restart during the wait re-checks.
+      void agent.whenIdle().then(() => {
+        if (state.loops.get(session.id) !== loop) return
+        if (loop.paused) {
+          loop.held = run
+          return
+        }
+        if (ctx.agents.get(session.id) !== agent) return
+        queueRound(agent, loop, run, [])
+      }, () => {})
+    })
+    return () => {
+      offTurn?.()
+      for (const d of disposers) d()
+      // Drop the driven loops with the plugin: a round still waiting on
+      // quiescence must not queue into an unloaded row, and a remount re-adopts
+      // any live loop from the durable fold anyway.
+      state.loops.clear()
+    }
+  })
+}

package/lib/client.js

@@ -0,0 +1,140 @@
+/**
+ * dsh-loop: browser half.
+ *
+ * The loop pill in the conversation.input.dock strip (same dock as the goal
+ * bar). Live state arrives through `useProjection('loop')`: the host half
+ * registers a projection unit folding the loop's own command rows and round
+ * relay lines, so the pill needs no polling and survives page reloads. Stop submits the host-side
+ * `/loop stop` command (a plugin command, not a model turn).
+ *
+ * Plain JavaScript on purpose: the client module system serves this file as a
+ * lazy-CJS factory on `window.__ModuleLoader__`; `react` is provided.
+ */
+
+window.__ModuleLoader__.load({
+  id: '@maci0/dsh-loop',
+
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    const React = require('react')
+    const createElement = React.createElement
+
+    // Full-width bar matching the goal bar's dock geometry (GoalBar.module.css:
+    // same 36px bar, 12px radius, tip background, centered column). The dock
+    // stack is vertical and full-width, so a fit-content chip floats left;
+    // the bar fills the column exactly like the goal widget does.
+    const CSS = [
+      '.loop-dock{box-sizing:border-box;width:calc(100% - var(--dsh-composer-side-clearance) - var(--dsh-composer-side-clearance) - var(--dsh-composer-dock-inset) - var(--dsh-composer-dock-inset) - var(--dsh-composer-dock-inset) - var(--dsh-composer-dock-inset));margin:0 auto}',
+      '.loop-pill{box-sizing:border-box;display:flex;align-items:center;gap:10px;width:100%;max-width:calc(var(--dsh-composer-card-max-width) - 4 * var(--dsh-composer-dock-inset));height:36px;margin:0 auto;padding:4px 5px 4px 12px;border:0.5px solid var(--dsw-alias-border-l1);border-radius:12px;background:var(--dsw-specific-tip)}',
+      '.loop-pill-paused{opacity:.75}',
+      '.loop-glyph{display:inline-flex;flex:none;color:var(--dsw-alias-label-tertiary)}',
+      '.loop-label{flex:1;min-width:0;font-size:13px;font-weight:500;line-height:24px;color:var(--dsw-alias-label-primary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}',
+      '.loop-rounds{flex:none;font-size:12px;color:var(--dsw-alias-label-tertiary)}',
+      '.loop-btn{flex:none;appearance:none;font:inherit;font-size:12px;padding:2px 10px;cursor:pointer;color:var(--dsw-alias-label-primary);background:none;border:1px solid var(--dsw-alias-border-l2);border-radius:999px}',
+      '.loop-btn:disabled{cursor:default;opacity:.5}',
+      '.loop-error{color:var(--dsw-alias-label-error)}',
+    ].join('')
+
+    if (typeof document !== 'undefined') {
+      const style = document.createElement('style')
+      style.textContent = CSS
+      document.head.append(style)
+    }
+
+    /** Rounds text: 0 means forever. */
+    const roundsText = (rounds) => (rounds === 0 ? '∞' : `${rounds}`)
+
+    /**
+     * Run a pill verb (`/loop pause | resume | stop`) for one session. A
+     * failure never rejects out of the click handler: it lands in the pill as
+     * `{ verb, message, loop }`, shown while the projected loop is the one the
+     * verb failed on. The next action clears it.
+     * @param {Function} run - the injected runner.
+     * @param {string} sessionId - the dock's session.
+     * @param {string} verb - pause, resume, or stop.
+     * @param {object} loop - the projected loop the verb acts on.
+     * @param {Function} setPending - the pending flag setter.
+     * @param {Function} setFailure - the failure setter.
+     */
+    const runVerb = async (run, sessionId, verb, loop, setPending, setFailure) => {
+      setPending(verb)
+      setFailure(null)
+      try {
+        await run(sessionId, verb)
+      } catch (error) {
+        setFailure({ verb, message: error instanceof Error ? error.message : String(error), loop })
+      } finally {
+        setPending(null)
+      }
+    }
+
+    /** Button copy for a verb, reused in the failure label. */
+    const VERB_LABEL = { pause: 'Pause', resume: 'Resume', stop: 'Stop' }
+
+    /**
+     * The pill: visible while a loop is active or paused in this session,
+     * mirroring the goal bar's pause/resume/stop verbs.
+     * @param {object} props - standard dock props (sessionId, useProjection)
+     *   plus the injected verb runner.
+     */
+    function LoopPill({ sessionId, useProjection, onLoop }) {
+      const loop = useProjection('loop')
+      const [pending, setPending] = React.useState(null)
+      const [failure, setFailure] = React.useState(null)
+
+      if (loop === undefined || loop === null || (loop.phase !== 'active' && loop.phase !== 'paused')) return null
+      const paused = loop.phase === 'paused'
+      // A projection change (a new loop reference) retires the failure.
+      const failed = failure !== null && failure.loop === loop ? failure : null
+      const verb = (name) => () => runVerb(onLoop, sessionId, name, loop, setPending, setFailure)
+
+      return createElement('div', { className: 'loop-dock' },
+        createElement('div', { className: paused ? 'loop-pill loop-pill-paused' : 'loop-pill' },
+          createElement('span', { className: 'loop-glyph' }, '⟳'),
+          failed === null
+            ? createElement('span', { className: 'loop-label', title: loop.command }, `${paused ? 'Paused · ' : ''}${loop.command}`)
+            : createElement('span', { className: 'loop-label loop-error', title: failed.message }, `${VERB_LABEL[failed.verb]} failed`),
+          createElement('span', { className: 'loop-rounds' }, ` ${loop.run}/${roundsText(loop.rounds)}`),
+          createElement('button', {
+            className: 'loop-btn',
+            onClick: verb(paused ? 'resume' : 'pause'),
+            disabled: pending !== null,
+          }, pending === 'pause' || pending === 'resume' ? '…' : paused ? 'Resume' : 'Pause'),
+          createElement('button', {
+            className: 'loop-btn',
+            onClick: verb('stop'),
+            disabled: pending !== null,
+          }, pending === 'stop' ? '…' : 'Stop'),
+        ),
+      )
+    }
+
+    exports.inject = ['slots', 'sessions']
+
+    /**
+     * Client plugin body: the loop pill dock entry.
+     * @param ctx - client root context.
+     */
+    function apply(ctx) {
+      ctx.slots.inject('conversation.input.dock', () => ctx.slots.register({
+        name: 'conversation.input.dock',
+        id: 'loop',
+        order: 11,
+        inject: (sessionId) => ({
+          onLoop: async (id, verb) => {
+            const binding = ctx.sessions.binding(id ?? sessionId)
+            if (binding === undefined) throw new Error(`dsh-loop: session "${id ?? sessionId}" is unavailable`)
+            const result = await binding.session.command(`/loop ${verb}`)
+            if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message}`)
+          },
+        }),
+      }, LoopPill))
+    }
+
+    exports.apply = apply
+    return module.exports
+  },
+})

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Loop",
+    "description": "Repeat a command across turns with /loop; /loop stop ends it."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "循环",
+    "description": "用 /loop 跨回合重复一条命令；/loop stop 结束。"
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@maci0/dsh-loop",
+  "version": "0.10.1",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "index.js",
+  "description": "/loop <rounds> <command> for DeepSeek Harness: repeat a command across agent turns; 0 loops forever, /loop stop ends it.",
+  "license": "MIT",
+  "exports": {
+    ".": "./index.js",
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./locale/*.json": "./locale/*.json",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-api-session-controller"
+      ]
+    },
+    "compatibility": {
+      "dsh": ">=0.2.0-rc.2 <0.3.0"
+    }
+  },
+  "files": [
+    "icon.svg",
+    "locale/*.json",
+    "index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:node": "node --test tests/*.test.*"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/maci0/dsh-loop.git"
+  },
+  "icon": "./icon.svg",
+  "dependencies": {
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.1",
+    "zod": "^4.4.3"
+  }
+}