dsh-plugin-prompt-tool 0.3.1 → 0.4.0

package/preset/context-gate.mjs

@@ -0,0 +1,165 @@
+/**
+ * anchored-context-gate — reusable unified injection control for ANY preset.
+ *
+ * Mount this one plugin to keep a session's first model request free of
+ * auto-injected context, whatever its source, and to have every injection
+ * return on the second round. It intercepts the harness's two unified
+ * injection paths — not a per-source denylist — so it covers sources that do
+ * not exist yet:
+ *
+ *  a. RUNTIME CONTEXT (system-prompt/assemble): while the session is
+ *     unpromoted, the assembly's `contexts` are blanked. That covers the
+ *     WHOLE `SystemPrompt.context()` family — the sandbox and approval
+ *     policy snapshots and any third-party context provider — without
+ *     enumerating them. The loop's own snapshot projection then emits no
+ *     message during the gate (no snapshot ever existed), and at the first
+ *     promoted request it emits exactly ONE fresh snapshot: "minimal first
+ *     round, inject on the second round" falls out of the projection's
+ *     diffing, with no reinjection logic here.
+ *
+ *  b. STEP MESSAGES (agent/pre-step): the waterfall payload carries the
+ *     CLAIMED message batch (the inbox messages this step owns). While
+ *     unpromoted, the gate keeps exactly the claimed messages plus a small
+ *     kind allowlist, and strips everything any listener appended — skill
+ *     catalog, AGENTS.md digest, time/tmux context, hooks, unknown
+ *     third-party plugins — by DEFAULT, regardless of source identity. The
+ *     default allowlist is `['skill-invocation']`: a user-initiated skill
+ *     gesture is not an automatic injection, and stripping it would lose the
+ *     skill content once the gesture scrolls out of the per-step claim.
+ *     Durable history (compaction summaries included) never passes through
+ *     this gate: it enters the request via the session surface, not the
+ *     pre-step waterfall.
+ *
+ * The phase is the same epoch-aware promotion machine the anchored presets
+ * use (see compaction-epoch.mjs): a durable `tool/call` and/or
+ * `assistant/message` (per `promoteOn`, default `either`) promotes, and a
+ * `compaction/end` boundary demotes again — the first post-compaction request
+ * is a "second first request" and is gated the same way. Derived from durable
+ * events, so resume and reload preserve it.
+ *
+ * SUBAGENTS: by default subagents (delegationDepth > 0) skip the gate (their
+ * first request already sees full context). `includeSubagents: true` gates
+ * them too — their first request is clean and their own first reply or tool
+ * call opens the gate — so a delegation cannot reintroduce an uncontrolled
+ * first request. Keep this flag in sync with any companion phase plugin
+ * (e.g. the tool-bootstrap row).
+ *
+ * CONFIG:
+ *  - `promoteOn`: 'either' (default) | 'tool-call' | 'assistant-message'.
+ *  - `includeSubagents`: boolean, default false.
+ *  - `enabled`: boolean, default true. `false` disables both interception
+ *    paths (A/B testing without touching the row set).
+ *  - `allowKinds`: message `source.kind` names allowed beyond the claimed
+ *    batch, default ['skill-invocation']. An explicitly empty array keeps
+ *    ONLY the claimed batch.
+ *
+ * ROW ORDER: mount this row FIRST in the composition. Waterfall after-next
+ * transforms apply in reverse registration order, so registering first (plus
+ * the pre-step listener's `prepend: true`) makes the gate the outermost
+ * transform — nothing registered later re-injects past it.
+ *
+ * Robustness: both filters degrade to "keep everything" on their own
+ * failures — a gate bug must never eat the user's context — and invalid
+ * config fails at apply time, i.e. at preset mount, where it is visible.
+ */
+
+import { createEpochPromotion } from './compaction-epoch.mjs'
+import { booleanOption, createWarnOnce, parsePromoteOn, validateConfig } from './shared.mjs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'anchored-context-gate'
+
+/**
+ * Deliberately NO inject list: the listeners only touch services at event
+ * time, and applying without an inject lets this row register before the
+ * context-injecting plugins (dsh-agent-instructions, dsh-tool-skill, host
+ * plane policy projections) when it sits first in the composition.
+ */
+export const inject = []
+
+/** Every config key this plugin accepts — anything else is a typo. */
+const ALLOWED_KEYS = new Set(['promoteOn', 'includeSubagents', 'enabled', 'allowKinds'])
+
+/**
+ * Message kinds allowed through the pre-step gate beyond the claimed batch.
+ * A user-initiated skill gesture is the only default entry: it is not an
+ * automatic injection (see the header note).
+ */
+const DEFAULT_ALLOW_KINDS = ['skill-invocation']
+
+
+/**
+ * Validate the kind allowlist. An explicitly empty array is meaningful: keep
+ * ONLY the claimed batch, stripping even user skill gestures.
+ */
+function allowKindList(value, field) {
+  if (value === undefined) return new Set(DEFAULT_ALLOW_KINDS)
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item.length === 0)) {
+    throw new TypeError(`${name}: ${field} must be an array of non-empty strings`)
+  }
+  return new Set(value)
+}
+
+
+/** Register the unified context gate. */
+export function apply(ctx, config) {
+  const source = validateConfig(name, config, ALLOWED_KEYS)
+  const promoteEvents = parsePromoteOn(name, source.promoteOn)
+  const includeSubagents = booleanOption(name, source.includeSubagents, 'includeSubagents', false)
+  const enabled = booleanOption(name, source.enabled, 'enabled', true)
+  const allowKinds = allowKindList(source.allowKinds, 'allowKinds')
+
+  const promotion = createEpochPromotion(promoteEvents, { includeSubagents })
+  ctx.on('session/event', (session, event) => promotion.observe(session, event))
+
+  const warnOnce = createWarnOnce(ctx, name)
+
+  // Path (a): blank the dynamic runtime-context contributions while the
+  // session is unpromoted. Covers the whole SystemPrompt.context() family
+  // without enumerating it; the loop's snapshot projection then stays silent
+  // and diffs exactly ONE fresh snapshot in at the first promoted request.
+  ctx.on('system-prompt/assemble', async (_assembly, context, next) => {
+    // Downstream errors propagate untouched; only this filter's own logic is guarded.
+    const assembled = await next()
+    if (enabled === false) return assembled
+    try {
+      if (promotion.status(context.agent).promoted) return assembled
+      if (!Array.isArray(assembled.contexts) || assembled.contexts.length === 0) return assembled
+      return { ...assembled, contexts: [] }
+    } catch (error) {
+      // A gate bug must never break assembly: degrade to the assembled value.
+      warnOnce(`${name}: runtime-context suppression failed, keeping contexts: ${String((error && error.message) || error)}`)
+      return assembled
+    }
+  })
+
+  // Path (b): claimed-baseline deny on the pre-step waterfall. The payload's
+  // `messages` is the batch this step CLAIMED from the inbox — the baseline
+  // every injection appends to. Keep that baseline plus the kind allowlist,
+  // strip every appended message regardless of its source identity.
+  ctx.on('agent/pre-step', async ({ agent, messages: claimed }, next) => {
+    // Downstream errors propagate untouched; only this filter's own logic is guarded.
+    const decision = await next()
+    if (decision.kind === 'reject') return decision
+    if (enabled === false) return decision
+    try {
+      if (promotion.status(agent).promoted) return decision
+      if (!Array.isArray(decision.messages)) return decision
+      if (!Array.isArray(claimed)) return decision
+      const baseline = new Set(claimed)
+      const baselineIds = new Set(claimed
+        .map((message) => message?.id)
+        .filter((id) => id !== undefined && id !== null))
+      const kept = decision.messages.filter((message) =>
+        baseline.has(message)
+        || (message?.id !== undefined && message?.id !== null && baselineIds.has(message.id))
+        || allowKinds.has(message?.source?.kind),
+      )
+      return kept.length === decision.messages.length ? decision : { ...decision, messages: kept }
+    } catch (error) {
+      // A gate bug must never eat context: degrade to keeping every message.
+      warnOnce(`${name}: pre-step gate failed, keeping injected context: ${String((error && error.message) || error)}`)
+      return decision
+    }
+  }, { prepend: true })
+}

package/preset/custom-bash.mjs

@@ -0,0 +1,243 @@
+/**
+ * custom-bash — a Windows-capable `bash` tool that registers under the SAME
+ * name (`bash`) as the official persistent bash, with a Minimal-compatible
+ * description, but executes through `ctx.subprocess.spawn` instead of a PTY.
+ *
+ * WHY: DeepSeek's first-request trajectory anchor keys on the tool SCHEMA
+ * matching the RL training distribution (issue #11: persistent
+ * bash + str_replace_editor anchored 5/5 at maxTokens=256000, pwsh/read
+ * 8/8 standard-like). The official persistent bash uses a PTY, and DSH's PTY
+ * backend is linux/darwin-only — `subprocess-local` throws "terminal
+ * inspection is unsupported on platform win32". A custom tool that presents
+ * the same name and a Minimal-like description but spawns Git Bash through
+ * the ordinary (cross-platform) subprocess seam keeps the schema anchor
+ * without the PTY dependency.
+ *
+ * Executable resolution (config `bashPath`, issue #24 — no hardcoded install
+ * path): an explicit non-empty `bashPath` wins unconditionally. Unset, the
+ * Git Bash executable is INFERRED, in probe order:
+ *  1. the `git` executable on PATH — its install root carries `bin\bash.exe`
+ *     one level up from `cmd\`, beside `bin\`, or two levels up from
+ *     `mingw64\bin\` (the standard installer, choco, and winget all resolve
+ *     here; a scoop SHIM does not — its directory is the shims root, not the
+ *     app — which is what step 2 covers);
+ *  2. the well-known Git-for-Windows roots derived from environment variables
+ *     (`ProgramFiles`, `ProgramFiles(x86)`, per-user `LOCALAPPDATA\Programs
+ *     \Git`, scoop's `~\scoop\apps\git\current` junction);
+ *  3. plain `bash` through `ctx.subprocess.resolveExecutable` (PATH lookup —
+ *     last resort, since on Windows that may pick the WSL shim; WSL bash is
+ *     still true bash, only the filesystem paths shift to /mnt/…).
+ *
+ * If NOTHING resolves, the tool fails with an actionable error naming the
+ * remedies — it does NOT silently execute under a different shell: the
+ * schema above promises `bash -c` semantics, and pwsh/cmd are different
+ * command languages. PowerShell stays available as its OWN tool (`pwsh`,
+ * present in the promoted catalog on Windows).
+ *
+ * Semantics mirror the official bash tool: `bash -c <command>` in a fresh
+ * process, bounded output, non-zero exit reported not thrown. No sandbox
+ * confinement on Windows (the sandbox backend is linux-only); the tool
+ * description says so. The bootstrap catalog pairs this with
+ * `str_replace_editor` (Minimal's two tools).
+ */
+
+import { access } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'custom-bash'
+
+/** The subprocess and tools services must exist before this tool can register. */
+export const inject = ['subprocess', 'tools']
+
+const DEFAULT_TIMEOUT_MS = 120000
+const DEFAULT_MAX_OUTPUT_BYTES = 64000
+
+/**
+ * Git Bash candidate paths, in probe order (see the header): the `git`
+ * executable's install root first, then the well-known env-derived roots.
+ * Exported for tests; pure — existence probing happens at the call site.
+ */
+export function bashCandidates(env, gitExe) {
+  const candidates = []
+  // git at <root>\cmd\git.exe (installer/scoop) or <root>\bin\git.exe →
+  // <root>\bin\bash.exe; <root>\mingw64\bin\git.exe (portable) → two up.
+  // A bare relative name means `git` did not actually resolve to a path.
+  if (typeof gitExe === 'string' && /[/\\]/.test(gitExe)) {
+    const dir = dirname(gitExe)
+    const root = dirname(dir)
+    candidates.push(
+      join(root, 'bin', 'bash.exe'),
+      join(dir, 'bash.exe'),
+      join(dirname(root), 'bin', 'bash.exe'),
+    )
+  }
+  if (env.ProgramFiles) candidates.push(join(env.ProgramFiles, 'Git', 'bin', 'bash.exe'))
+  if (env['ProgramFiles(x86)']) candidates.push(join(env['ProgramFiles(x86)'], 'Git', 'bin', 'bash.exe'))
+  if (env.LOCALAPPDATA) candidates.push(join(env.LOCALAPPDATA, 'Programs', 'Git', 'bin', 'bash.exe'))
+  if (env.USERPROFILE) candidates.push(join(env.USERPROFILE, 'scoop', 'apps', 'git', 'current', 'bin', 'bash.exe'))
+  // Layouts overlap (a `bin` git.exe derives the same bash twice) — probe
+  // order survives the dedupe, insertion order is preserved.
+  return [...new Set(candidates)]
+}
+
+/** Tool parameter schema for the model-facing command. */
+const commandSchema = {
+  type: 'object',
+  properties: {
+    command: {
+      type: 'string',
+      description: 'The bash command to execute (`bash -c` string domain).',
+    },
+    workdir: {
+      type: 'string',
+      description: 'Optional working directory; defaults to the session cwd.',
+    },
+  },
+  required: ['command'],
+  additionalProperties: false,
+}
+
+/** Register the model-facing `bash` tool. */
+export function apply(ctx, config) {
+  const explicitBashPath = typeof config?.bashPath === 'string' && config.bashPath.length > 0 ? config.bashPath : undefined
+  const timeoutMs = Number.isSafeInteger(config?.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS
+  const maxOutputBytes = Number.isSafeInteger(config?.maxOutputBytes) && config.maxOutputBytes > 0 ? config.maxOutputBytes : DEFAULT_MAX_OUTPUT_BYTES
+
+  // The inferred executable is memoized per plugin instance: candidate probing
+  // walks the filesystem, and the answer cannot change within a mount. A
+  // failed inference is NOT memoized — the plain `bash` fallback resolves
+  // fresh on every execute until some probe succeeds.
+  let inferredShell
+  const exists = (path) => access(path).then(() => true, () => false)
+  const resolveShell = async (signal) => {
+    if (explicitBashPath !== undefined) {
+      // A misconfigured explicit path must fail as itself, not as a
+      // discovery miss — the raw resolution error says which path failed.
+      return ctx.subprocess.resolveExecutable(explicitBashPath, undefined, signal)
+    }
+    if (inferredShell !== undefined) {
+      return ctx.subprocess.resolveExecutable(inferredShell, undefined, signal)
+    }
+    let gitExe
+    try {
+      gitExe = await ctx.subprocess.resolveExecutable('git', undefined, signal)
+    } catch {
+      // git unresolvable → the env-derived candidates below still apply
+    }
+    for (const candidate of bashCandidates(process.env, gitExe)) {
+      if (!(await exists(candidate))) continue
+      try {
+        inferredShell = await ctx.subprocess.resolveExecutable(candidate, undefined, signal)
+        return inferredShell
+      } catch {
+        // Exists but unresolvable (EPERM, a broken scoop junction): keep
+        // probing — one bad root must not block the rest of the chain, and
+        // nothing is memoized so later executes can still find a good one.
+        continue
+      }
+    }
+    try {
+      return await ctx.subprocess.resolveExecutable('bash', undefined, signal)
+    } catch (error) {
+      // Total discovery failure (no Git Bash root, no env root, no bash on
+      // PATH): name the remedies instead of leaking a raw ENOENT. Never
+      // fall back to pwsh/cmd here — the schema promises `bash -c`
+      // semantics; a different shell would silently break every command.
+      throw new Error(`bash executable not found — install Git for Windows, expose a bash on PATH, or set the custom-bash \`bashPath\` config (${String((error && error.message) || error)})`)
+    }
+  }
+
+  ctx.tools.register({
+    name: 'bash',
+    description: [
+      'Run commands in a bash shell (Git Bash on Windows)',
+      '* When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.',
+      "* You don't have access to the internet via this tool.",
+      '* You do have access to a mirror of common linux and python packages via apt and pip.',
+      '* State does NOT persist across command calls: each call runs in a fresh shell.',
+      "* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.",
+      '* Please avoid commands that may produce a very large amount of output.',
+      '* NOTE: runs without OS sandbox confinement on Windows (no landlock); treat output as untrusted.',
+    ].join('\n'),
+    parameters: commandSchema,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          text: { type: 'string' },
+        },
+        required: ['text'],
+      },
+      render: (_args, value) => [{ type: 'text', text: value.text }],
+    },
+    async execute(args, exec) {
+      const shell = await resolveShell(exec?.signal)
+      const workdir = typeof args.workdir === 'string' && args.workdir.length > 0
+        ? args.workdir
+        : exec?.agent?.session?.header?.cwd
+
+      // timeoutMs is a foreground deadline. subprocess only reacts to an abort
+      // signal, so we own the classification here: a timeout aborts the tree
+      // (SIGTERM -> grace -> SIGKILL), then the error below says WHY.
+      const abort = new AbortController()
+      let timedOut = false
+      const timer = setTimeout(() => {
+        timedOut = true
+        abort.abort(new Error(`bash timed out after ${timeoutMs}ms`))
+      }, timeoutMs)
+      const onExecAbort = () => abort.abort(exec?.signal?.reason)
+      if (exec?.signal?.aborted) onExecAbort()
+      else exec?.signal?.addEventListener('abort', onExecAbort, { once: true })
+
+      let outcome
+      try {
+        const handle = ctx.subprocess.spawn({
+          argv: [shell, '-c', args.command],
+          ...workdir !== undefined ? { cwd: workdir } : {},
+          stdio: {
+            stdin: 'ignore',
+            stdout: { maxBytes: maxOutputBytes },
+            stderr: { maxBytes: maxOutputBytes },
+          },
+          signal: abort.signal,
+          graceMs: 3000,
+        })
+        try {
+          outcome = await handle.done
+        } catch (error) {
+          // A spawn-level failure (bad executable, EPERM) surfaces as a throw,
+          // which the runtime turns into an isError result.
+          throw new Error(`bash spawn failed: ${String(error)}`)
+        }
+        let stdout = ''
+        let stderr = ''
+        try {
+          stdout = handle.collected.stdout.readFrom(0).text
+          stderr = handle.collected.stderr.readFrom(0).text
+        } catch {
+          // Collected readers may be unavailable on some backends; tolerate.
+        }
+        const text = [stdout, stderr].filter((part) => part.length > 0).join('\n')
+        const tail = text.length > 0 ? text : `exit code: ${outcome.exitCode} (no output)`
+        if (timedOut) {
+          throw new Error(`bash timed out after ${timeoutMs}ms${tail ? `\n${tail}` : ''}`)
+        }
+        if (exec?.signal?.aborted) {
+          const reason = exec.signal.reason
+          throw new Error(`bash aborted: ${reason instanceof Error ? reason.message : String(reason ?? 'aborted')}`)
+        }
+        if (outcome.exitCode !== 0) {
+          // Non-zero exit is a reported failure, not a throw: the model sees the
+          // command output plus the exit code.
+          throw new Error(tail)
+        }
+        return { text: tail }
+      } finally {
+        clearTimeout(timer)
+        exec?.signal?.removeEventListener('abort', onExecAbort)
+      }
+    },
+  })
+}

package/preset/instruction-hint.mjs

@@ -0,0 +1,217 @@
+/**
+ * instruction-hint — replace `dsh-agent-instructions`' full AGENTS.md/CLAUDE.md
+ * injection with a minimal "these files exist" hint.
+ *
+ * WHY: the full workspace-instruction digest is a large injected block. After
+ * the anchored bootstrap promotes, we want the model to KNOW the instruction
+ * files exist (so it reads them before acting) without dumping their content
+ * into every request. The model reads the files itself via the filesystem
+ * tools when it needs them.
+ *
+ * Behavior:
+ *  - After the session records its first durable promotion signal
+ *    (`promoteOn`, default `either`), ONE hint message is injected, listing
+ *    which instruction files were found:
+ *      - user-global: `$DSH_HOME/AGENTS.md`
+ *      - project chain: AGENTS.md / CLAUDE.md / AGENTS.local.md / CLAUDE.local.md
+ *        walking up from the session cwd to the project root (a directory
+ *        containing `.git`, or the cwd itself).
+ *  - The hint is ONCE PER SESSION, DERIVED FROM DURABLE EVENTS: the guard
+ *    scans the session log for an existing `instruction-hint` message (then
+ *    O(1)), so a process restart — whose in-memory state starts empty —
+ *    cannot inject a second copy. A duplicate would collide with the first
+ *    message's deterministic id (`instruction-hint-<sessionId>`) and break
+ *    history replay.
+ *  - The hint instructs the model to READ the files before acting when
+ *    relevant, without embedding their content.
+ *  - Files are probed via `ctx.fs` (the host filesystem seam); a missing fs
+ *    service or an unreadable probe degrades to no hint (never throws).
+ *  - Pre-promotion requests get NO hint (matches the anchored bootstrap).
+ *  - Subagents skip the phase wait by default (their first request already
+ *    counts as promoted); `includeSubagents: true` makes a subagent's own
+ *    first reply or tool call open the hint — which also keeps the injection
+ *    out of the context gate's stripped first request (the gate strips
+ *    non-claimed messages while unpromoted).
+ *
+ * ROW ORDER: this plugin registers its `agent/pre-step` handler with
+ * `prepend: true` and after `context-gate`/`tool-bootstrap`, so it runs
+ * inside the gate's outermost strip — but it emits AFTER promotion, when the
+ * strip is inactive. The hint source kind is `instruction-hint`, which is
+ * not in the gate's claimed-baseline allowlist, so the gate can strip it
+ * only while the session is unpromoted (never the intended path).
+ */
+
+import { readFileSync } from 'node:fs'
+import { createEpochPromotion } from './compaction-epoch.mjs'
+import { booleanOption, createWarnOnce, parsePromoteOn, validateConfig } from './shared.mjs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'instruction-hint'
+
+/** Optional prompt-tool hint text (agents-instruction.txt beside this module). */
+function readAgentsInstructionText() {
+  try {
+    return readFileSync(new URL('./agents-instruction.txt', import.meta.url), 'utf8').trim()
+  } catch {
+    return ''
+  }
+}
+
+/** Candidate file names, in probe order, for the project chain and user-global. */
+const PROJECT_CANDIDATES = ['AGENTS.md', 'CLAUDE.md', 'AGENTS.local.md', 'CLAUDE.local.md']
+const USER_GLOBAL_CANDIDATE = 'AGENTS.md'
+
+
+/** Every config key this plugin accepts — anything else is a typo. */
+const ALLOWED_KEYS = new Set(['promoteOn', 'includeSubagents'])
+
+
+/** Find the project root: first ancestor containing any root marker (e.g. .git). */
+async function findProjectRoot(fs, cwd, signal) {
+  let current = cwd
+  for (;;) {
+    for (const marker of ['.git', '.hg', '.svn']) {
+      try {
+        const target = await fs.resolve(joinPath(current, marker), { cwd, signal })
+        const info = await fs.stat(target, signal)
+        if (info !== undefined) return current
+      } catch {
+        // Probe failure = marker absent; continue.
+      }
+    }
+    const parent = parentPath(current)
+    if (parent === current || parent.length === 0) return cwd
+    current = parent
+  }
+}
+
+/** List instruction files present in one directory (project candidates). */
+async function presentInDir(fs, dir, candidates, signal) {
+  const found = []
+  for (const candidate of candidates) {
+    try {
+      const target = await fs.resolve(joinPath(dir, candidate), { cwd: dir, signal })
+      const info = await fs.stat(target, signal)
+      if (info !== undefined && info.type === 'file') found.push(candidate)
+    } catch {
+      // Absent or unreadable — skip.
+    }
+  }
+  return found
+}
+
+/** Join one path segment onto a directory (platform-agnostic string join). */
+function joinPath(dir, segment) {
+  if (dir.endsWith('/') || dir.endsWith('\\')) return dir + segment
+  const sep = dir.includes('\\') ? '\\' : '/'
+  return dir + sep + segment
+}
+
+/** Parent of an absolute Windows or POSIX path. */
+function parentPath(path) {
+  const idx = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
+  if (idx <= 0) return path
+  const parent = path.slice(0, idx)
+  return parent.length === 0 ? path : parent
+}
+
+/** Register the post-promotion instruction-hint injector. */
+export function apply(ctx, config) {
+  const source = validateConfig(name, config, ALLOWED_KEYS)
+  const promoteEvents = parsePromoteOn(name, source.promoteOn)
+  const includeSubagents = booleanOption(name, source.includeSubagents, 'includeSubagents', false)
+  const agentsInstructionText = readAgentsInstructionText()
+  const promotion = createEpochPromotion(promoteEvents, { includeSubagents })
+  ctx.on('session/event', (session, event) => promotion.observe(session, event))
+
+  /**
+   * Sessions whose hint is already durable in the event log — the
+   * restart-safe replacement for an in-memory "already hinted" set. Seeded by
+   * a one-time scan, then maintained incrementally through `session/event`.
+   */
+  const hinted = new Map()
+  const hintIsDurable = (session) => {
+    const known = hinted.get(session.id)
+    if (known !== undefined) return known
+    const found = (Array.isArray(session.events) ? session.events : []).some((event) =>
+      event.type === 'user/message' && event.data?.source?.kind === 'instruction-hint',
+    )
+    hinted.set(session.id, found)
+    return found
+  }
+  ctx.on('session/event', (session, event) => {
+    if (event.type === 'user/message' && event.data?.source?.kind === 'instruction-hint') {
+      hinted.set(session.id, true)
+    }
+  })
+
+  const warnOnce = createWarnOnce(ctx, name)
+
+  ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+    const decision = await next()
+    try {
+      if (promotion.status(agent).promoted !== true) return decision
+      const session = agent.session
+      if (session === undefined || hintIsDurable(session)) return decision
+      hinted.set(session.id, true)
+
+      if (agentsInstructionText.length > 0) {
+        return {
+          ...decision,
+          messages: [...decision.messages, {
+            id: `instruction-hint-${session.id}`,
+            role: 'user',
+            content: [{ type: 'text', text: agentsInstructionText }],
+            source: { kind: 'instruction-hint', form: 'hint' },
+          }],
+        }
+      }
+
+      const fs = ctx.get('fs')
+      if (fs === undefined) return decision
+      const cwd = session.header.cwd ?? process.cwd()
+
+      const projectFiles = []
+      const root = await findProjectRoot(fs, cwd, signal)
+      projectFiles.push(...await presentInDir(fs, root, PROJECT_CANDIDATES, signal))
+
+      const userGlobalFiles = []
+      try {
+        const dshHome = process.env.DSH_HOME ?? (process.env.USERPROFILE ? `${process.env.USERPROFILE}\\.dsh` : undefined)
+        if (dshHome !== undefined) {
+          userGlobalFiles.push(...await presentInDir(fs, dshHome, [USER_GLOBAL_CANDIDATE], signal))
+        }
+      } catch {
+        // Unreadable home probe — ignore.
+      }
+
+      const sections = []
+      if (projectFiles.length > 0) {
+        sections.push(`Workspace instruction files exist: ${projectFiles.join(', ')} (project root: ${root}).`)
+      }
+      if (userGlobalFiles.length > 0) {
+        sections.push(`A user-global instruction file exists: ${USER_GLOBAL_CANDIDATE}.`)
+      }
+      if (sections.length === 0) return decision
+
+      const text = [
+        ...sections,
+        'Do NOT assume their content. When a task touches this workspace, read the relevant instruction files first and follow them.',
+      ].join(' ')
+
+      return {
+        ...decision,
+        messages: [...decision.messages, {
+          id: `instruction-hint-${session.id}`,
+          role: 'user',
+          content: [{ type: 'text', text }],
+          source: { kind: 'instruction-hint', form: 'hint' },
+        }],
+      }
+    } catch (error) {
+      // A hint bug must never hurt the session: skip the hint.
+      warnOnce(`${name}: hint injection failed, skipping: ${String((error && error.message) || error)}`)
+      return decision
+    }
+  }, { prepend: true })
+}

package/preset/near-anchor.mjs

@@ -15,6 +15,8 @@
  * false（默认）时忽略 anchorText，按任务与模型自动选择文本。
  */
 
+import { extractText, isDelegated, newMessageId } from './shared.mjs'
+
 /** Cordis 插件名，供 loader 诊断使用。 */
 export const name = 'near-anchor'
 
@@ -33,23 +35,8 @@ const ANCHOR_INSPECT = "Start your reasoning with the exact sentence: 'We need t
 /** 复杂规划类：放行 Let 深度规划路径。 */
 const ANCHOR_DEEP = "Start your reasoning with the exact sentence: 'Let me think through the design before changing anything.'"
 
-/** 生成消息 id：优先加密随机 id，旧运行时回退到随机串。 */
-function newMessageId() {
-  return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-    ? crypto.randomUUID()
-    : `near-anchor-${Date.now()}-${Math.random().toString(36).slice(2)}`
-}
-
-/** 从 user/message 的 data 中提取纯文本；兼容 data.message 嵌套形状。 */
-function extractText(data) {
-  if (!data) return ''
-  const payload = data && typeof data.message === 'object' && data.message !== null ? data.message : data
-  const content = Array.isArray(payload.content) ? payload.content : []
-  return content.map((block) => (typeof block === 'string' ? block : (block?.text ?? ''))).join(' ').trim()
-}
-
 /** 按开关与任务选择锚点：useCustom=true 固定用自定义；false 自动选择。 */
-function chooseAnchor(text, modelId, customText, useCustom) {
+function chooseAnchor(text, customText, useCustom) {
   if (useCustom === true) {
     return typeof customText === 'string' ? customText.trim() : ''
   }
@@ -83,7 +70,7 @@ export function apply(ctx, config) {
     const session = agent.session
     if (session === undefined || handled.has(session.id) || seenAnchor(session)) return decision
     // 子代理不注入锚点：让 dsh-mnemon 等结构化 worker 按自己的提示词工作。
-    if ((session.header?.delegationDepth ?? 0) > 0) return decision
+    if (isDelegated(session)) return decision
 
     const messages = Array.isArray(decision.messages) ? decision.messages : []
     // 只锚真实用户消息；插件消息原样保留。
@@ -92,12 +79,12 @@ export function apply(ctx, config) {
     const taskText = extractText(messages[userIndex])
     if (taskText.length === 0) return decision
 
-    const anchorText = chooseAnchor(taskText, agent.options?.model, customText, useCustom)
+    const anchorText = chooseAnchor(taskText, customText, useCustom)
     if (anchorText.length === 0) return decision
     handled.add(session.id)
 
     const anchor = {
-      id: newMessageId(),
+      id: newMessageId('near-anchor'),
       role: 'user',
       content: [{ type: 'text', text: anchorText }],
       source: {