dsh-human-wait 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.0 — 2026-10-26
+
+First release.
+
+- Pauses the PTC `run_code` execution deadline while DSH is waiting for a human:
+  `ptcRuntime.run` is wrapped so the wall-clock budget is measured by this plugin and only
+  charged while no human-interaction wait is pending.
+- Recognises human waits through `userQuestions.ask`, `userQuestions.askTimed` and
+  `approval.request`; wait accounting is scoped to the waiting run with `AsyncLocalStorage`.
+- `humanWaitCapMs` (default 24 h, `-1` = uncapped) bounds how long a run may wait.
+- `enabled` / `humanWaitCapMs` options; all wrappers are restored when the plugin unloads.
+- No sampling interval: the deadline is re-armed on accounting events, not on a tick.
+- Fail-open: missing services, unavailable `AbortSignal.any` or an unexpected runtime shape
+  leave the shipped deadline in place and log a single warning.
+- Bundle patch inserts one host row; no client half.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-human-wait contributors
+
+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

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# dsh-human-wait
+
+**Stops the PTC `run_code` deadline while DSH is waiting for you.** In PTC mode a question
+(`ask_user_question`), the plan review raised by `exit_plan_mode`, or a sandbox approval is a
+nested call inside the one `run_code` program — and `dsh-ptc-runtime-node` measures a single
+wall-clock budget across the whole program, *including the time you spend answering*. Wait
+longer than what is left of that budget and the run dies with:
+
+```
+Error: code run failed (timeout): execution deadline reached (120000ms)
+```
+
+and the question card is reported as **已中断 / interrupted**. This plugin keeps the deadline
+for execution but pauses it while a human-interaction wait is pending. A runaway program is
+still cut off after its budget; a question you think about for an hour is not.
+
+> 中文摘要：PTC 模式下提问、计划审批和批准都是 `run_code` 里的嵌套调用，共用同一条 120 秒墙钟预算，
+> 所以「想久一点再回答」会让你看到的是一次 `execution deadline reached (120000ms)` 超时。本插件
+> 保留执行的截止时间，但在**等待你回答/批准期间暂停计时**；等待本身另有上限（默认 24 小时，可设为无限）。
+
+---
+
+## What it does
+
+| Situation | Without the plugin | With the plugin |
+| --- | --- | --- |
+| A question inside `run_code`, you answer in 20 s, run budget was 120 s | OK | OK |
+| Same run, you answer after 4 minutes | run aborted at 120 s, question interrupted | run keeps waiting; the answer is delivered |
+| Same run, you never answer | run aborted at 120 s | run aborted once the wait exceeds `humanWaitCapMs` (24 h) |
+| A program that spins for 10 minutes without asking anything | aborted at 120 s | aborted at 120 s — unchanged |
+
+It works by:
+
+1. wrapping `ptcRuntime.run` and moving the deadline into the plugin, so it can be paused;
+2. wrapping `userQuestions.ask` / `userQuestions.askTimed` and `approval.request` — the three
+   service calls that exist only because a human is being waited on;
+3. charging the budget only while no such wait is pending (`node:async_hooks`
+   `AsyncLocalStorage` keeps the accounting scoped to the run that is actually waiting).
+
+A single `run_code` call can still pass its own `timeoutMs`; that number keeps working as the
+execution budget and is what the plugin enforces.
+
+## Install
+
+The plugin is a normal DSH bundle (one inserted host row, no client half). Pick one route:
+
+**A. From a tarball, by hand.** In `<DSH_HOME>/profiles/<profile>/package.json` add the dependency
+and the bundle name, then install it:
+
+```jsonc
+{
+  "dependencies": {
+    "dsh-human-wait": "file:D:/path/to/dsh-human-wait-0.1.0.tgz"
+  },
+  "dsh": { "profile": { "bundles": ["dsh-human-wait"] } }
+}
+```
+
+```powershell
+# pnpm ships with the desktop runtime
+& "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\pnpm\pnpm.cjs" install --dir "$env:USERPROFILE\.dsh\profiles\desktop"
+```
+
+**B. From the registry, once published.** Use the Plugins settings page (or a
+`plugin_manager install_bundle` call in a session) with the spec `dsh-human-wait@0.1.0`; the
+plugin manager adds both the dependency and the bundle entry for you.
+
+Then **quit DSH from the tray icon and start it again** — bundles are composed at boot. The
+Electron-managed profile cannot be booted through the `dsh` CLI (`profile "desktop" is managed
+exclusively by the Electron application`), so restarting the app is the only way to apply it.
+Removing the bundle name from `dsh.profile.bundles` and deleting the dependency disables the
+plugin again; the wrappers are also restored at unload time.
+
+## Configuration
+
+The row ships sensible defaults; override them in the same profile's `cordis.patch.yml` when
+you want something else:
+
+```yaml
+- id: human-wait
+  name: 'dsh-human-wait'
+  config:
+    enabled: true
+    humanWaitCapMs: 86400000   # 24 h; -1 = no cap at all
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `true` | Turn the pause on/off. `false` reproduces the shipped behaviour exactly. |
+| `humanWaitCapMs` | `86400000` | Longest time one run may spend waiting for a human. `-1` removes the cap. |
+
+How the clock works: the plugin re-arms a single timer on every accounting event (run start, a
+wait starting or ending, or the timer itself firing), so there is no fixed sampling period and
+no configuration knob for one.
+
+Changes are read when the plugin loads, so restart DSH after editing.
+
+## What counts as a human wait
+
+- `userQuestions.ask` — blocking questions, including the `plan-review` question from
+  `exit_plan_mode`;
+- `userQuestions.askTimed` — timed questions;
+- `approval.request` — sandbox/policy approvals that block on the user.
+
+Tool calls that finish on their own (bash, file reads, web fetches, subagents) are **not**
+waits: their time is still charged to the run, exactly as before.
+
+## Behaviour notes
+
+- **Fail-open.** If `ptcRuntime` / `userQuestions` / `approval` are missing, if
+  `AbortSignal.any` is unavailable, or if a wrapper cannot be installed, the plugin logs one
+  warning and leaves the shipped deadline untouched.
+- **Restored on unload.** Every wrapper is removed when the plugin unloads (or is disabled and
+  the profile restarted); the original methods are back.
+- **The terminal error changes kind.** When the paused execution budget runs out, the runtime
+  reports `kind: "abort"` instead of `kind: "timeout"`, because the plugin aborts the run
+  through its signal. The message still contains `execution deadline reached (<budget>ms)`, so
+  the surfaced text is the same.
+- **Only PTC sessions are affected.** Standard sessions never had this timeout: their
+  questions wait indefinitely by design.
+- **Not a public extension point.** The plugin patches methods of two host services
+  (`ptcRuntime`, `userQuestions`) and one approval service. That is the only way to implement
+  this today; a future DSH release may change those internals and make the patch a no-op. The
+  plugin is written so that this failure mode is safe, not fatal.
+
+Verified against DSH desktop **0.2.1-rc.3** (`dsh-ptc-runtime-node` 0.2.1, node 24.21).
+`ptc-runtime-node/lib/index.js` is where the shipped timer lives:
+
+```js
+const wallTimer = spec.timeoutMs === null ? void 0 : setTimeout(() => {
+  timedOut = true;
+  controller.abort("execution deadline reached");
+}, spec.timeoutMs);
+```
+
+## Troubleshooting
+
+- Look for `[dsh-human-wait]` lines in the DSH log; the plugin logs either
+  `PTC run deadlines now pause while a human is waiting (wait cap: …)` or the reason it stayed
+  out of the way.
+- If a wait still dies with `execution deadline reached`, the wrapper did not see the wait.
+  Check that PTC mode is actually in use (the session header shows the `PTC` badge) and that
+  `enabled` is not `false`.
+
+## Development
+
+```powershell
+npm test        # node --test, no dependencies
+```
+
+## License
+
+MIT
+
+## Acceptance record
+
+Recorded 2026-10-26 against `dsh-human-wait` 0.1.0 in the desktop profile (PTC mode, shipped 120 s budget):
+
+| Test | Scenario | Observed |
+| --- | --- | --- |
+| A | nested `ask_user_question`, answered after 294037 ms | answer delivered, run continued, no `execution deadline reached` |
+| B | plan review submitted through `exit_plan_mode`, approved after 313073 ms | plan approved, run continued, no automatic cancellation at 120 s |
+| C | `run_code` running `while (true) {}` | killed after ~120 s with `Error: code run failed (abort): execution deadline reached (120000ms)` |
+
+Test C's `(abort)` label is expected — the plugin aborts through its own signal, so the runtime classifies the failure as `abort` instead of `timeout` while the message text stays `execution deadline reached (120000ms)`.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/cordis.patch.yml

@@ -0,0 +1,25 @@
+# dsh-human-wait — the PTC run deadline stops while you are being asked.
+#
+# PTC mode gives the model one tool, `run_code`. Questions (`ask_user_question`)
+# and the plan review raised by `exit_plan_mode` are nested calls inside that
+# program, and `dsh-ptc-runtime-node` wraps the whole program in one wall-clock
+# deadline (default 120000 ms) that explicitly includes "nested tool and
+# approval waits". A slow answer therefore shows up as
+#   Error: code run failed (timeout): execution deadline reached (120000ms)
+# and the question card is interrupted.
+#
+# The inserted row is the host half. It wraps `ptcRuntime.run` (deadline moved
+# into the plugin so it can pause), and `userQuestions.ask` / `askTimed` plus
+# `approval.request` (the signal that a human is being waited on).
+#
+# Defaults: `humanWaitCapMs` 86400000 (24 h), `enabled` true.
+# Set `humanWaitCapMs: -1` for no cap at all. Any other run budget (for example
+# `timeoutMs` passed to a single `run_code` call) is still honoured for the
+# time the program actually spends executing: the plugin re-arms the deadline
+# on every accounting event, so it does not resample on a timer.
+- insert:
+    - id: human-wait
+      name: 'dsh-human-wait'
+      config:
+        enabled: true
+        humanWaitCapMs: 86400000

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" fill="none">
+  <rect x="1" y="1" width="62" height="62" rx="14" fill="#111827"/>
+  <circle cx="32" cy="32" r="19" stroke="#7DD3FC" stroke-width="3"/>
+  <path d="M32 21V32L40 37" stroke="#7DD3FC" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  <rect x="44" y="17" width="4" height="12" rx="2" fill="#FDE68A"/>
+  <rect x="50" y="17" width="4" height="12" rx="2" fill="#FDE68A"/>
+</svg>

package/index.js

@@ -0,0 +1,423 @@
+/**
+ * dsh-human-wait — let PTC runs wait for you.
+ *
+ * PTC mode hands the model a single tool, `run_code`, and every nested call
+ * (`ask_user_question`, the plan review raised by `exit_plan_mode`, sandbox
+ * approvals) executes inside that one program. `dsh-ptc-runtime-node` puts one
+ * wall-clock deadline around the whole program — 120 s by default, and its own
+ * description says it includes "nested tool and approval waits". So the moment
+ * a question takes longer than the remaining budget, the run dies with
+ * `Error: code run failed (timeout): execution deadline reached (120000ms)` and
+ * the question card is reported as interrupted.
+ *
+ * This plugin keeps that deadline but pauses it while DSH is actually waiting
+ * for a human: it wraps `ptcRuntime.run` and runs the same budget itself, and
+ * wraps `userQuestions.ask` / `userQuestions.askTimed` / `approval.request` to
+ * learn when a human-interaction wait is pending. Time spent waiting is not
+ * charged to the run; time spent executing still is, so a runaway program is
+ * still cut off exactly as before. Waiting itself is capped by
+ * `humanWaitCapMs` (default 24 h, `-1` = no cap).
+ *
+ * Everything here is fail-open: if a service is missing, if the wrappers were
+ * already installed by someone else, or if a future DSH release changes these
+ * internals, the plugin logs once and leaves the shipped behaviour untouched.
+ * Every wrapper is removed when the plugin unloads.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+export const name = 'dsh-human-wait'
+
+/** Marks a wrapper this plugin installed, so patching twice is a no-op. */
+const PATCHED = Symbol.for('dsh-human-wait.patched')
+
+const DEFAULT_HUMAN_WAIT_CAP_MS = 24 * 60 * 60 * 1000
+const MAX_TIMER_MS = 2_147_483_647
+const DEADLINE_MESSAGE = 'execution deadline reached'
+
+/** Per-run wait accounting; a run has a slot only while it is on the stack. */
+const runScope = new AsyncLocalStorage()
+
+let Schema
+try {
+  const loaded = await import('@deepseek-ai/schemastery')
+  Schema = loaded.default ?? loaded.Schema
+} catch {
+  // A link-installed bundle must not require the host's packages; the plugin
+  // still works with its defaults when schemastery cannot be resolved.
+  Schema = undefined
+}
+
+export const Config = Schema === undefined
+  ? undefined
+  : Schema.object({
+    enabled: Schema.boolean().default(true)
+      .description('Pause the PTC run deadline while a human-interaction wait is pending.'),
+    humanWaitCapMs: Schema.number().default(DEFAULT_HUMAN_WAIT_CAP_MS)
+      .description('Longest time a run may spend waiting for a human, in milliseconds. -1 removes the cap.'),
+  })
+
+/**
+ * Resolve a possibly volatile config value (`Settings` may wrap it in a ref).
+ * @param {object} source
+ * @param {string} key
+ */
+function readScalar(source, key) {
+  const value = source[key]
+  if (value !== null && typeof value === 'object') {
+    if (typeof value.get === 'function') return value.get()
+    if (typeof value.value !== 'undefined') return value.value
+  }
+  return value
+}
+
+/**
+ * Normalise the plugin config into the values the wrappers use.
+ * @param {unknown} config
+ * @returns {{ enabled: boolean, humanWaitCapMs: number }}
+ */
+export function normalizeConfig(config) {
+  const source = config !== null && typeof config === 'object' ? config : {}
+
+  const rawEnabled = readScalar(source, 'enabled')
+  const enabled = typeof rawEnabled === 'boolean' ? rawEnabled : true
+
+  const rawCap = readScalar(source, 'humanWaitCapMs')
+  let humanWaitCapMs = DEFAULT_HUMAN_WAIT_CAP_MS
+  if (rawCap === -1) humanWaitCapMs = -1
+  else if (typeof rawCap === 'number' && Number.isFinite(rawCap) && rawCap > 0) {
+    humanWaitCapMs = Math.min(Math.round(rawCap), MAX_TIMER_MS)
+  }
+
+  return { enabled, humanWaitCapMs }
+}
+
+/** @param {unknown} value */
+function isThenable(value) {
+  return value !== null && typeof value === 'object' && typeof value.then === 'function'
+}
+
+/** @param {unknown} error */
+function messageOf(error) {
+  if (error instanceof Error) return error.message
+  if (typeof error === 'string') return error
+  try {
+    return String(error)
+  } catch {
+    return 'unknown error'
+  }
+}
+
+/**
+ * @param {object} ctx
+ * @returns {{ info: Function, warn: Function }}
+ */
+function createLogger(ctx) {
+  const noop = () => {}
+  try {
+    const factory = ctx?.logger
+    if (typeof factory === 'function') {
+      const scoped = factory('dsh-human-wait')
+      if (scoped !== null && typeof scoped === 'object') {
+        return {
+          info: typeof scoped.info === 'function' ? (...args) => scoped.info(...args) : noop,
+          warn: typeof scoped.warn === 'function' ? (...args) => scoped.warn(...args) : noop,
+        }
+      }
+    }
+    if (factory !== null && typeof factory === 'object' && typeof factory.info === 'function') {
+      return {
+        info: (...args) => factory.info(...args),
+        warn: typeof factory.warn === 'function' ? (...args) => factory.warn(...args) : noop,
+      }
+    }
+  } catch {
+    // fall through to the console fallback
+  }
+  return {
+    info: (...args) => console.log('[dsh-human-wait]', ...args),
+    warn: (...args) => console.warn('[dsh-human-wait]', ...args),
+  }
+}
+
+/**
+ * Where to install a method wrapper: the instance itself when the method is an
+ * own property, otherwise the class prototype the traceable proxy reads from.
+ * @param {object} host
+ * @param {string} key
+ */
+function methodHolder(host, key) {
+  if (host === null || typeof host !== 'object') return undefined
+  if (typeof host[key] !== 'function') return undefined
+  if (Object.hasOwn(host, key)) return host
+  const prototype = Object.getPrototypeOf(host)
+  if (prototype !== null && prototype !== undefined && typeof prototype[key] === 'function') return prototype
+  return host
+}
+
+/** @param {unknown} candidate */
+function isPatched(candidate) {
+  return typeof candidate === 'function' && candidate[PATCHED] === true
+}
+
+/**
+ * Mark a run's wait bookkeeping active for the duration of `callback`.
+ * @template T
+ * @param {{ waiters: number, schedule: () => void }} state
+ * @param {() => T} callback
+ * @returns {T}
+ */
+function withRunScope(state, callback) {
+  return runScope.run(state, callback)
+}
+
+/**
+ * Register one human-interaction wait in the active run scope. Returns the
+ * function that closes it; undefined when the call is not inside a PTC run.
+ */
+function enterHumanWait() {
+  const state = runScope.getStore()
+  if (state === undefined) return undefined
+  state.schedule() // settle executing time up to this instant
+  state.waiters += 1
+  state.schedule() // arm the wait cap
+  let left = false
+  return () => {
+    if (left) return
+    left = true
+    state.schedule() // settle the wait (waiters is still > 0 here)
+    state.waiters = Math.max(0, state.waiters - 1)
+    state.schedule() // resume the execution budget
+  }
+}
+
+/**
+ * Wrap one asynchronous method so callers' time is not charged to the run.
+ * @param {object} host
+ * @param {string} key
+ * @param {object} logger
+ */
+function patchWaitMethod(host, key, logger) {
+  const holder = methodHolder(host, key)
+  if (holder === undefined) return undefined
+
+  const original = holder[key]
+  if (isPatched(original)) return undefined
+
+  const wrapped = function patchedHumanWait(...args) {
+    const leave = enterHumanWait()
+    let result
+    try {
+      result = Reflect.apply(original, this, args)
+    } catch (error) {
+      leave?.()
+      throw error
+    }
+    if (isThenable(result)) {
+      return result.then(
+        (value) => {
+          leave?.()
+          return value
+        },
+        (error) => {
+          leave?.()
+          throw error
+        },
+      )
+    }
+    leave?.()
+    return result
+  }
+  wrapped[PATCHED] = true
+
+  try {
+    holder[key] = wrapped
+  } catch (error) {
+    logger.warn(`could not wrap ${key}: ${messageOf(error)}`)
+    return undefined
+  }
+
+  return () => {
+    if (holder[key] === wrapped) holder[key] = original
+  }
+}
+
+/**
+ * Wrap the run method: the runtime keeps its compile/validation, the deadline
+ * moves into this plugin so it can be paused.
+ * @param {object} runtime
+ * @param {{ humanWaitCapMs: number }} settings
+ * @param {object} logger
+ */
+function patchRun(runtime, settings, logger) {
+  const holder = methodHolder(runtime, 'run')
+  if (holder === undefined) return undefined
+
+  const original = holder.run
+  if (isPatched(original)) return undefined
+  if (typeof globalThis.AbortSignal?.any !== 'function') {
+    logger.warn('AbortSignal.any is unavailable — leaving the shipped PTC deadline in place')
+    return undefined
+  }
+
+  const wrapped = function patchedRun(spec) {
+    const budget = spec !== null && typeof spec === 'object' ? spec.timeoutMs : undefined
+    if (typeof budget !== 'number' || !Number.isFinite(budget) || budget <= 0) {
+      return Reflect.apply(original, this, [spec])
+    }
+    try {
+      return runWithPausedDeadline(original, this, spec, budget, settings, logger)
+    } catch (error) {
+      logger.warn(`could not wrap run: ${messageOf(error)} — using the shipped deadline`)
+      return Reflect.apply(original, this, [spec])
+    }
+  }
+  wrapped[PATCHED] = true
+
+  try {
+    holder.run = wrapped
+  } catch (error) {
+    logger.warn(`could not wrap run: ${messageOf(error)}`)
+    return undefined
+  }
+
+  return () => {
+    if (holder.run === wrapped) holder.run = original
+  }
+}
+
+/**
+ * Run one program with a deadline that only advances while no human wait is
+ * pending. The timer is re-armed whenever a wait starts or ends, so the budget
+ * expires at the exact instant the executing time runs out.
+ * @param {Function} original
+ * @param {unknown} self
+ * @param {object} spec
+ * @param {number} budget
+ * @param {{ humanWaitCapMs: number }} settings
+ * @param {object} logger
+ */
+function runWithPausedDeadline(original, self, spec, budget, settings, logger) {
+  const controller = new AbortController()
+  const outer = spec.signal
+  const signal = outer === undefined ? controller.signal : AbortSignal.any([outer, controller.signal])
+  const cap = settings.humanWaitCapMs === -1 ? Infinity : settings.humanWaitCapMs
+
+  let remaining = budget
+  let waited = 0
+  let last = Date.now()
+  let timer
+  let aborted = false
+  let finished = false
+
+  const state = {
+    waiters: 0,
+    schedule: () => {},
+  }
+
+  const stop = () => {
+    if (timer !== undefined) {
+      clearTimeout(timer)
+      timer = undefined
+    }
+  }
+  const settle = () => {
+    const now = Date.now()
+    const elapsed = Math.max(0, now - last)
+    last = now
+    if (state.waiters > 0) waited += elapsed
+    else remaining -= elapsed
+  }
+  const expire = (reason) => {
+    if (aborted || finished) return
+    aborted = true
+    stop()
+    controller.abort(reason)
+  }
+  const arm = (delay) => {
+    stop()
+    if (aborted || finished || !Number.isFinite(delay)) return
+    timer = setTimeout(schedule, Math.max(1, Math.ceil(delay)))
+    timer.unref?.()
+  }
+  const schedule = () => {
+    if (aborted || finished) return
+    settle()
+    if (state.waiters > 0) {
+      if (waited >= cap) {
+        expire(`human interaction wait exceeded (${cap}ms)`)
+        return
+      }
+      arm(cap - waited)
+      return
+    }
+    if (remaining <= 0) {
+      expire(`${DEADLINE_MESSAGE} (${budget}ms)`)
+      return
+    }
+    arm(remaining)
+  }
+  state.schedule = schedule
+
+  let result
+  try {
+    result = withRunScope(state, () => {
+      schedule()
+      return Reflect.apply(original, self, [{ ...spec, timeoutMs: null, signal }])
+    })
+  } catch (error) {
+    finished = true
+    stop()
+    throw error
+  }
+
+  return Promise.resolve(result).finally(() => {
+    finished = true
+    stop()
+  })
+}
+
+/**
+ * @param {object} ctx
+ * @param {object} config
+ */
+export function apply(ctx, config) {
+  const settings = normalizeConfig(config)
+  const logger = createLogger(ctx)
+
+  if (!settings.enabled) {
+    logger.info('disabled by config — leaving the shipped PTC deadline in place')
+    return
+  }
+
+  ctx.inject(['ptcRuntime', 'userQuestions'], (child) => {
+    child.effect(() => {
+      const disposers = []
+      try {
+        for (const key of ['ask', 'askTimed']) {
+          const dispose = patchWaitMethod(child.userQuestions, key, logger)
+          if (dispose !== undefined) disposers.push(dispose)
+        }
+        const dispose = patchRun(child.ptcRuntime, settings, logger)
+        if (dispose !== undefined) {
+          disposers.push(dispose)
+          const cap = settings.humanWaitCapMs === -1 ? 'unlimited' : `${settings.humanWaitCapMs} ms`
+          logger.info(`PTC run deadlines now pause while a human is waiting (wait cap: ${cap})`)
+        } else {
+          logger.warn('ptcRuntime.run was not patched — human waits will still count against the run deadline')
+        }
+      } catch (error) {
+        logger.warn(`setup failed: ${messageOf(error)} — leaving the shipped PTC deadline in place`)
+        for (const dispose of disposers.reverse()) dispose()
+        return () => {}
+      }
+      return () => {
+        for (const dispose of disposers.reverse()) dispose()
+      }
+    })
+  })
+
+  ctx.inject(['approval'], (child) => {
+    child.effect(() => patchWaitMethod(child.approval, 'request', logger) ?? (() => {}))
+  })
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Human wait",
+    "description": "Pauses the PTC run deadline while DSH is waiting for you to answer a question, review a plan or approve a request — instead of reporting `execution deadline reached (120000ms)`."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "人机等待",
+    "description": "DSH 在等你回答问题、审阅计划或批准请求时暂停 PTC 运行截止计时，不再把等待报成 `execution deadline reached (120000ms)`。"
+  }
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "dsh-human-wait",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Pauses the PTC run_code deadline while DSH is waiting for you to answer a question, review a plan or approve a request, so long human waits are no longer reported as `execution deadline reached (120000ms)`.",
+  "license": "MIT",
+  "author": {
+    "name": "SpaceRelay",
+    "url": "https://github.com/SpaceRelay"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SpaceRelay/dsh-subagent-control.git",
+    "directory": "human-wait"
+  },
+  "homepage": "https://github.com/SpaceRelay/dsh-subagent-control/tree/main/human-wait#readme",
+  "bugs": {
+    "url": "https://github.com/SpaceRelay/dsh-subagent-control/issues"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "icon": "./icon.svg",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "ptc",
+    "human-in-the-loop",
+    "timeout",
+    "ask-user-question",
+    "plan-mode"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.2.1-rc.1 <0.3.0-0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/plugin.test.mjs"
+  }
+}