@lijian-ui/dsh-file-manager 0.1.20

package/src/host/git-runner.ts

@@ -0,0 +1,116 @@
+// Generated by scripts/sync-shared.mjs from shared/host/git-runner.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Shared host git subprocess plumbing: the run result shape, the runner seam,
+ * the collected-output cap, and the production runner over the subprocess
+ * service. Packages receive this file as a generated copy via
+ * scripts/sync-shared.mjs; edit the shared source and re-run the sync instead
+ * of editing a copy.
+ *
+ * The context shape is declared structurally so this module stays
+ * self-contained (shared/ has no cordis dependency): any context whose
+ * `subprocess` satisfies SubprocessServiceLike works, which the plugin
+ * contexts do.
+ * @module dsh-web-ui-shared/host/git-runner
+ */
+
+/** One finished git invocation. */
+export interface GitRunResult {
+  exitCode: number | null
+  stdout: string
+  stderr: string
+}
+
+/** The spawn seam the service runs git through (subprocess service in production). */
+export interface GitRunner {
+  run(argv: readonly string[], cwd: string): Promise<GitRunResult>
+}
+
+/** Collected-output cap for one git command. */
+export const OUTPUT_CAP_BYTES = 1 << 20
+
+/** The subprocess service surface this runner consumes (structural). */
+export interface SubprocessServiceLike {
+  spawn(spec: {
+    argv: readonly string[]
+    cwd: string
+    stdio: {
+      stdin: 'ignore'
+      stdout: { maxBytes: number }
+      stderr: { maxBytes: number }
+    }
+    graceMs: number
+  }): {
+    done: Promise<{ exitCode: number | null }>
+    collected: {
+      stdout?: { readFrom(offset: number): { text: string } }
+      stderr?: { readFrom(offset: number): { text: string } }
+    }
+  }
+}
+
+/** Per-package knobs for the shared production runner. */
+export interface GitRunnerOptions {
+  /** Build the full spawn argv from the git args (default ['git', ...argv]). */
+  spawnArgv?: (argv: readonly string[]) => readonly string[]
+  /** degrade turns spawn/run failures into exitCode 127 results instead of throwing. */
+  failureMode?: 'throw' | 'degrade'
+  /** console.error tag for degrade mode. */
+  errorTag?: string
+}
+
+/**
+ * Production runner over the subprocess service: one managed child per
+ * command, bounded collect on both streams. Degrade mode keeps the SCM tab
+ * showing the friendly "not a git repository" state instead of a bare 400
+ * when git is missing or the subprocess service fails.
+ * @param ctx - context carrying the subprocess service.
+ * @param options - per-package behavior knobs.
+ * @returns the runner.
+ */
+export function subprocessRunner(ctx: { subprocess: SubprocessServiceLike }, options: GitRunnerOptions = {}): GitRunner {
+  const spawnArgv = options.spawnArgv ?? ((argv) => ['git', ...argv])
+  const degrade = options.failureMode === 'degrade'
+  const errorTag = options.errorTag ?? 'git'
+  const failure = (prefix: string, error: unknown): GitRunResult => ({
+    exitCode: 127,
+    stdout: '',
+    stderr: prefix + (error instanceof Error ? error.message : String(error)),
+  })
+  return {
+    async run(argv, cwd) {
+      const spec = {
+        argv: spawnArgv(argv),
+        cwd,
+        stdio: {
+          stdin: 'ignore' as const,
+          stdout: { maxBytes: OUTPUT_CAP_BYTES },
+          stderr: { maxBytes: OUTPUT_CAP_BYTES },
+        },
+        graceMs: 10_000,
+      }
+      if (degrade) {
+        let handle
+        try {
+          handle = ctx.subprocess.spawn(spec)
+        } catch (error) {
+          console.error('[' + errorTag + '] git spawn failed:', error)
+          return failure('git: spawn failed: ', error)
+        }
+        try {
+          const outcome = await handle.done
+          const stdout = handle.collected.stdout?.readFrom(0).text ?? ''
+          const stderr = handle.collected.stderr?.readFrom(0).text ?? ''
+          return { exitCode: outcome.exitCode, stdout, stderr }
+        } catch (error) {
+          console.error('[' + errorTag + '] git run failed:', error)
+          return failure('git: run failed: ', error)
+        }
+      }
+      const handle = ctx.subprocess.spawn(spec)
+      const outcome = await handle.done
+      const stdout = handle.collected.stdout?.readFrom(0).text ?? ''
+      const stderr = handle.collected.stderr?.readFrom(0).text ?? ''
+      return { exitCode: outcome.exitCode, stdout, stderr }
+    },
+  }
+}

package/src/host/git-service.ts

@@ -0,0 +1,395 @@
+/**
+ * Host git service for the SCM tab: working-tree status (porcelain v1, -z),
+ * stage/unstage/discard batches, all scoped to the gated project root and
+ * executed through the managed subprocess seam. Parsing is pure and exported
+ * for tests; the service only wraps the runner. Discard never touches the
+ * staged side (the index is only ever rewritten by stage/unstage), matching
+ * the "discard = worktree side" contract.
+ * @module dsh-filemgr/host/git-service
+ */
+
+import { join, relative } from 'node:path'
+import { realpath } from 'node:fs/promises'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-subprocess'
+import { subprocessRunner as sharedSubprocessRunner, type GitRunResult, type GitRunner } from './git-runner.ts'
+import type { GitBatchResult, GitChangeRow, GitFileState, GitStatusView, PanelError } from '../core/types.ts'
+import { isPathInside, type WorkspaceGate } from './gate.ts'
+
+/** One finished git invocation (shared runner plumbing). */
+export type { GitRunResult, GitRunner } from './git-runner.ts'
+
+/** TTL for a positive repo-top-level verdict. */
+const REPO_CACHE_TTL_MS = 60_000
+/** TTL for a negative (null) repo-top-level verdict. */
+const NO_REPO_CACHE_TTL_MS = 30_000
+
+/** Production runner over `ctx.subprocess`: shared plumbing, degrade mode for the SCM tab. */
+export function subprocessRunner(ctx: Context): GitRunner {
+  return sharedSubprocessRunner(ctx, { failureMode: 'degrade', errorTag: 'dsh-filemgr' })
+}
+
+/** Map one porcelain letter to the row state (unknown letters stay unknown). */
+export function porcelainState(letter: string): GitFileState {
+  switch (letter) {
+    case 'A': return 'created'
+    case 'M': return 'modified'
+    case 'D': return 'deleted'
+    case 'R': return 'renamed'
+    case 'C': return 'created'
+    case 'U': return 'conflicted'
+    case '?': return 'untracked'
+    default: return 'unknown'
+  }
+}
+
+/**
+ * Parse `git status --porcelain=v1 -z` output into staged/unstaged/untracked
+ * rows. With -z every entry is NUL-terminated; rename entries carry two paths
+ * (old and new). Pure — exported for tests.
+ * @param output - raw porcelain v1 -z output.
+ * @returns the three change groups.
+ */
+export function parsePorcelain(output: string): {
+  staged: GitChangeRow[]
+  unstaged: GitChangeRow[]
+  untracked: GitChangeRow[]
+} {
+  const staged: GitChangeRow[] = []
+  const unstaged: GitChangeRow[] = []
+  const untracked: GitChangeRow[] = []
+  if (output === '') return { staged, unstaged, untracked }
+  const fields = output.split('\0')
+  for (let i = 0; i < fields.length; i += 1) {
+    const field = fields[i]
+    if (field === '') continue
+    const x = field[0] ?? ' '
+    const y = field[1] ?? ' '
+    const path = field.slice(3)
+    if (x === '?' && y === '?') {
+      untracked.push({ path, state: 'untracked', staged: false })
+      continue
+    }
+    if (x === 'R' || x === 'C') {
+      // -z rename entries: XY old\0new — the path field holds the old path.
+      const oldPath = path
+      const newPath = fields[i + 1] ?? oldPath
+      i += 1
+      staged.push({ path: newPath, oldPath, state: porcelainState(x), staged: true })
+      if (y !== ' ') {
+        unstaged.push({ path: newPath, oldPath, state: porcelainState(y), staged: false })
+      }
+      continue
+    }
+    if (x !== ' ') {
+      staged.push({ path, state: porcelainState(x), staged: true })
+    }
+    if (y !== ' ') {
+      unstaged.push({ path, state: porcelainState(y), staged: false })
+    }
+  }
+  return { staged, unstaged, untracked }
+}
+
+/** Parse the porcelain row set into the status view shape. */
+export function parseStatusView(root: string, branch: string, output: string): GitStatusView {
+  const { staged, unstaged, untracked } = parsePorcelain(output)
+  return { root, branch, staged, unstaged, untracked }
+}
+
+/** The not-a-repository verdict for status reads. */
+const NO_REPO: PanelError = { code: 'git-unavailable', message: 'not a git repository' }
+
+/**
+ * Workspace-scoped git operations. Gated methods pass the gate, resolve the
+ * repository root, and reject non-repositories with a stable error; the
+ * `Canonical` variants trust an already-gated canonical root (the SSE poll)
+ * and skip the gate.
+ * @param runner - the spawn seam.
+ * @param gate - workspace-membership gate.
+ * @param fsDelete - delete seam for untracked discard (host: FsService.delete).
+ */
+export class GitService {
+  constructor(
+    private readonly runner: GitRunner,
+    private readonly gate: WorkspaceGate,
+    private readonly fsDelete: (root: string, rel: string) => Promise<{ ok: true } | PanelError>,
+  ) {}
+
+  /** Cached one-shot git binary probe; never re-probes after the first call. */
+  private availablePromise: Promise<boolean> | undefined
+
+  /**
+   * Cached repo-top-level resolution per canonical workspace, with a TTL so
+   * running `git init` (positive self-heal) or deleting `.git` (negative
+   * self-heal) is discovered by a later probe. Positive verdicts live 60s,
+   * negative (null) verdicts 30s; exitCode 127 is never cached because it
+   * means spawn/run failed rather than "not a repository".
+   */
+  private readonly repoCache = new Map<string, { value: Promise<string | null>; expiresAt: number }>()
+
+  /**
+   * Probe the git binary once (git --version) and cache the verdict for the
+   * service lifetime. A machine without git then degrades every operation to
+   * the stable "not a git repository" state after a single failed spawn,
+   * instead of re-spawning ENOENT on every poll tick. The cache stays false
+   * even if git is installed later; the host restart picks it up.
+   */
+  gitAvailable(): Promise<boolean> {
+    if (this.availablePromise === undefined) {
+      this.availablePromise = this.runner
+        .run(['--version'], '/')
+        .then((result) => result.exitCode === 0)
+        .catch(() => false)
+    }
+    return this.availablePromise
+  }
+
+  /**
+   * Resolve the repo top-level for one canonical root. Verdicts are cached
+   * with a TTL: a positive repo path for 60s, a negative null for 30s. After
+   * expiry the next call re-runs `rev-parse --show-toplevel`, so a repo
+   * created or removed while the host is running is picked up later. An
+   * exitCode 127 means the spawn/run itself failed; it returns null but is
+   * deliberately not cached so the next call retries. Any other failure is
+   * cached as a negative verdict for its TTL.
+   */
+  private repoOf(root: string): Promise<string | null> {
+    const now = Date.now()
+    const cached = this.repoCache.get(root)
+    if (cached !== undefined && cached.expiresAt > now) return cached.value
+    // Infinity while the probe is in flight: concurrent callers share the
+    // same promise, and the real TTL is stamped once the verdict settles.
+    const entry: { value: Promise<string | null>; expiresAt: number } = {
+      value: Promise.resolve(null),
+      expiresAt: Number.POSITIVE_INFINITY,
+    }
+    entry.value = this.run(['rev-parse', '--show-toplevel'], root)
+      .then((result) => {
+        if (result.exitCode === 127) {
+          // Spawn/run failure is not a repo verdict: leave nothing cached.
+          if (this.repoCache.get(root) === entry) this.repoCache.delete(root)
+          return null
+        }
+        if (result.exitCode !== 0) {
+          entry.expiresAt = now + NO_REPO_CACHE_TTL_MS
+          return null
+        }
+        const repo = result.stdout.trim()
+        const found = repo !== '' && isPathInside(repo, root) ? repo : null
+        entry.expiresAt = now + (found === null ? NO_REPO_CACHE_TTL_MS : REPO_CACHE_TTL_MS)
+        return found
+      })
+      .catch(() => {
+        entry.expiresAt = now + NO_REPO_CACHE_TTL_MS
+        return null
+      })
+    this.repoCache.set(root, entry)
+    return entry.value
+  }
+
+  /**
+   * Whether an already-gated canonical root is a git repository. Skips the
+   * workspace gate so the SSE poll does not double-gate every 2s tick; the
+   * underlying repoOf cache keeps rev-parse probes at TTL cadence.
+   */
+  isRepositoryCanonical(canonicalRoot: string): Promise<boolean> {
+    return this.repoOf(canonicalRoot).then((repo) => repo !== null)
+  }
+
+  /**
+   * Whether a workspace root is a git repository. Gates the root first (POST
+   * route entry point); the SSE poll should use `isRepositoryCanonical`.
+   */
+  async isRepository(root: string): Promise<boolean> {
+    const gated = await this.gate(root)
+    if (!gated.ok) return false
+    return await this.isRepositoryCanonical(gated.canonical)
+  }
+
+  /** Resolve the gated canonical root and the repository top-level. */
+  private async repo(root: string): Promise<{ ok: true; root: string; repo: string } | { ok: false; error: PanelError }> {
+    const gated = await this.gate(root)
+    if (!gated.ok) return { ok: false, error: gated.error }
+    const repo = await this.repoOf(gated.canonical)
+    if (repo === null) return { ok: false, error: NO_REPO }
+    return { ok: true, root: gated.canonical, repo }
+  }
+
+  /** Run one git invocation and classify failures. */
+  private async run(argv: readonly string[], cwd: string): Promise<GitRunResult> {
+    return this.runner.run(argv, cwd)
+  }
+
+  /** The repo status view; null when the root is not a repository. */
+  async status(root: string): Promise<GitStatusView | null | PanelError> {
+    // A missing git binary answers before any spawn: the probe runs once per
+    // service lifetime, so a git-less machine never re-spawns ENOENT here.
+    if (!(await this.gitAvailable())) return null
+    const repo = await this.repo(root)
+    if (!repo.ok) return repo.error.code === 'git-unavailable' ? null : repo.error
+    return this.statusAt(repo.root, repo.repo)
+  }
+
+  /**
+   * The repo status view for an already-gated canonical root; null when it is
+   * not a repository. Skips the workspace gate (SSE subscribers were gated at
+   * connect) and reuses the same repoOf cache + status parsing as `status`.
+   */
+  async statusCanonical(canonicalRoot: string): Promise<GitStatusView | null> {
+    const repo = await this.repoOf(canonicalRoot)
+    if (repo === null) return null
+    return this.statusAt(canonicalRoot, repo)
+  }
+
+  /** Run branch + porcelain status for one resolved repo and parse the view. */
+  private async statusAt(root: string, repo: string): Promise<GitStatusView> {
+    const [branchResult, statusResult] = await Promise.all([
+      this.run(['rev-parse', '--abbrev-ref', 'HEAD'], repo),
+      this.run(['status', '--porcelain=v1', '-z', '--untracked-files=all'], repo),
+    ])
+    const branch = branchResult.stdout.trim() === 'HEAD' ? '' : branchResult.stdout.trim()
+    return parseStatusView(root, branch, statusResult.stdout)
+  }
+
+  /** The repo root for the watch layer (null when not a repository). */
+  async repoRoot(root: string): Promise<string | null> {
+    const repo = await this.repo(root)
+    return repo.ok ? repo.repo : null
+  }
+
+  /**
+   * The unified diff of one path ('' when there is no diff to show). Staged
+   * paths diff the index against HEAD (`--cached`); unstaged paths diff the
+   * worktree against the index. Untracked paths have no index/HEAD entry, so
+   * they diff against /dev/null (the canonical new-file shape); its exit code
+   * is 1 — differences exist — which is a success here, not a failure.
+   */
+  async diff(root: string, path: string, staged: boolean): Promise<{ content: string } | PanelError> {
+    const repo = await this.repo(root)
+    if (!repo.ok) return repo.error
+    const abs = join(repo.repo, path)
+    if (!isPathInside(repo.repo, abs)) return { code: 'path-outside-root', message: 'path outside the repository' }
+    const rel = relative(repo.repo, abs)
+    const tracked = await this.run(['ls-files', '--error-unmatch', '--', rel], repo.repo)
+    const result = tracked.exitCode !== 0
+      ? await this.run(['diff', '--no-index', '--', '/dev/null', rel], repo.repo)
+      : staged
+        ? await this.run(['diff', '--cached', '--', rel], repo.repo)
+        : await this.run(['diff', '--', rel], repo.repo)
+    // --no-index reports exit 1 when differences exist; a plain diff exits 0.
+    if (result.exitCode !== 0 && result.exitCode !== 1) {
+      return { code: 'git-failed', message: 'git diff failed' }
+    }
+    return { content: result.stdout }
+  }
+
+  /** Verify paths stay inside the repo root (defense in depth). */
+  private pathsInside(repo: string, paths: string[]): string[] {
+    const abs = paths.map((p) => join(repo, p))
+    return abs.filter((p) => isPathInside(repo, p)).map((p) => p)
+  }
+
+  /** Stage paths (git add). Batch result reflects the post-op status. */
+  async stage(root: string, paths: string[]): Promise<GitBatchResult | PanelError> {
+    return this.batch(root, paths, async (repo, inside) => {
+      const result = await this.run(['add', '--', ...inside], repo)
+      return result.exitCode === 0
+    })
+  }
+
+  /** Unstage paths (git restore --staged). */
+  async unstage(root: string, paths: string[]): Promise<GitBatchResult | PanelError> {
+    return this.batch(root, paths, async (repo, inside) => {
+      const result = await this.run(['restore', '--staged', '--', ...inside], repo)
+      return result.exitCode === 0
+    })
+  }
+
+  /**
+   * Discard paths (worktree side only). Tracked paths are restored from the
+   * index; untracked paths are deleted through the fs seam. The batch reports
+   * applied/failed per path.
+   */
+  async discard(root: string, paths: string[]): Promise<GitBatchResult | PanelError> {
+    const repo = await this.repo(root)
+    if (!repo.ok) return repo.error
+    const inside = this.pathsInside(repo.repo, paths)
+    const applied: string[] = []
+    const failed: string[] = []
+    // Membership is checked on the ABSOLUTE path (pathsInside resolves); the
+    // git commands below run with the repo-relative path (cwd = repo).
+    const eligible: string[] = []
+    for (const p of paths) {
+      if (inside.includes(join(repo.repo, p))) eligible.push(p)
+      else failed.push(p)
+    }
+    // One ls-files classifies every eligible path (its output IS the tracked
+    // set) instead of one --error-unmatch spawn per path.
+    const trackedSet = new Set<string>()
+    if (eligible.length > 0) {
+      const listed = await this.run(['ls-files', '-z', '--', ...eligible.map(p => ':(literal)' + p)], repo.repo)
+      for (const entry of listed.stdout.split('\0')) if (entry !== '') trackedSet.add(entry)
+    }
+    const tracked = eligible.filter(p => trackedSet.has(p))
+    const untracked = eligible.filter(p => !trackedSet.has(p))
+    // Tracked paths restore in one spawn; a batch failure falls back to
+    // per-path restores so the applied/failed split stays exact.
+    if (tracked.length > 0) {
+      const restored = await this.run(['restore', '--worktree', '--', ...tracked.map(p => ':(literal)' + p)], repo.repo)
+      if (restored.exitCode === 0) {
+        applied.push(...tracked)
+      } else {
+        for (const p of tracked) {
+          const single = await this.run(['restore', '--worktree', '--', ':(literal)' + p], repo.repo)
+          if (single.exitCode === 0) applied.push(p)
+          else failed.push(p)
+        }
+      }
+    }
+    for (const p of untracked) {
+      // Untracked paths are not restored by git restore; delete them directly.
+      // A symlink entry pointing outside the repo must not be deleted — the
+      // fs delete would follow the link away. Realpath-check before deleting.
+      try {
+        const real = await realpath(join(repo.repo, p))
+        if (!isPathInside(repo.repo, real)) {
+          failed.push(p)
+          continue
+        }
+      } catch {
+        // The path does not exist on disk (ENOENT): nothing to escape.
+      }
+      // The fs seam addresses the project ROOT (which may be a subdir of
+      // the repo); derive the root-relative path from the absolute one.
+      const rel = relative(repo.root, join(repo.repo, p))
+      // Untracked files that lie outside the session root cannot be deleted
+      // through the fs seam; refuse rather than delete a look-alike path.
+      if (rel === '..' || rel.startsWith('../')) {
+        failed.push(p)
+        continue
+      }
+      const deleted = await this.fsDelete(repo.root, rel)
+      if ('ok' in deleted && deleted.ok) applied.push(p)
+      else failed.push(p)
+    }
+    return { applied, failed }
+  }
+
+  /** Shared batch plumbing: gate, repo resolve, path filter, run the op. */
+  private async batch(
+    root: string,
+    paths: string[],
+    op: (repo: string, inside: string[]) => Promise<boolean>,
+  ): Promise<GitBatchResult | PanelError> {
+    const repo = await this.repo(root)
+    if (!repo.ok) return repo.error
+    const inside = this.pathsInside(repo.repo, paths)
+    const ok = inside.length > 0 ? await op(repo.repo, inside) : true
+    if (!ok) return { code: 'git-failed', message: 'git operation failed' }
+    // Report the REQUESTED (repo-relative) spellings, not the resolved absolutes.
+    const applied = ok ? paths.filter((p) => inside.includes(join(repo.repo, p))) : []
+    const failed = paths.filter((p) => !inside.includes(join(repo.repo, p)))
+    return { applied, failed }
+  }
+}

package/src/host/loopback.ts

@@ -0,0 +1,63 @@
+// Generated by scripts/sync-shared.mjs from shared/host/loopback.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Loopback trust fence shared by the host route families: socket address,
+ * Host header, and browser same-origin markers. Packages receive this file as
+ * a generated copy via scripts/sync-shared.mjs; edit the shared source and
+ * re-run the sync instead of editing a copy.
+ *
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
+ * markers (sec-fetch-site and Origin) for the request-level fence.
+ * @module dsh-web-ui-shared/host/loopback
+ */
+
+import type { IncomingMessage } from 'node:http'
+
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+export function isIPv4Loopback(v4: string): boolean {
+  const parts = v4.split('.')
+  return parts.length === 4
+    && parts[0] === '127'
+    && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+export function isLoopbackAddress(address: string | undefined): boolean {
+  if (address === undefined) return false
+  const normalized = address.toLowerCase()
+  if (normalized === '::1') return true
+  if (normalized.startsWith('::ffff:')) return isIPv4Loopback(normalized.slice('::ffff:'.length))
+  return isIPv4Loopback(normalized)
+}
+
+/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
+export function isLoopbackHostname(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  return isIPv4Loopback(hostname)
+}
+
+/**
+ * Request-level trust fence: a loopback socket address AND a loopback Host
+ * header, plus browser same-origin markers. The socket address is
+ * authoritative; X-Forwarded-For is never trusted.
+ */
+export function isLoopbackRequest(request: IncomingMessage): boolean {
+  if (!isLoopbackAddress(request.socket.remoteAddress)) return false
+  const host = request.headers.host
+  if (typeof host !== 'string') return false
+  let hostUrl: URL
+  try {
+    hostUrl = new URL('http://' + host)
+  } catch {
+    return false
+  }
+  if (!isLoopbackHostname(hostUrl.hostname)) return false
+  if (request.headers['sec-fetch-site'] === 'cross-site') return false
+  const origin = request.headers.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}

package/src/host/poll-guard.ts

@@ -0,0 +1,109 @@
+// Generated by scripts/sync-shared.mjs from shared/host/poll-guard.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Poll-loop guard shared by the plugin family's Host halves (git-graph,
+ * filemgr): one bounded refresh loop that never overlaps itself,
+ * backs off on consecutive failures, and stops at a global deadline. Pure
+ * logic with injectable timers, so consumers test it without wall clocks.
+ */
+
+/** Timer injection seam; defaults to the global setTimeout/clearTimeout pair. */
+export interface PollTimers {
+  /** Schedule fn(ms). */
+  set: (fn: () => void, ms: number) => unknown
+  /** Cancel a scheduled handle. */
+  clear: (handle: unknown) => void
+}
+
+const DEFAULT_TIMERS: PollTimers = {
+  set: (fn, ms) => setTimeout(fn, ms),
+  clear: (handle) => { clearTimeout(handle as ReturnType<typeof setTimeout>) },
+}
+
+export interface PollGuardOptions {
+  /** Base interval between runs. */
+  intervalMs: number
+  /** Runs stop entirely once this much wall time passed since start(). */
+  deadlineMs: number
+  /** Cap for the failure backoff; each consecutive failure doubles the delay up to this. */
+  maxBackoffMs: number
+  /** Optional timer seam for tests. */
+  timers?: PollTimers
+  /** Invoked once when the deadline fires; no run starts afterwards. */
+  onDeadline?: () => void
+  /** Invoked after a run settles with the consecutive-failure count. */
+  onSettled?: (consecutiveFailures: number) => void
+  /** The task each tick runs; a rejection counts as a failure. */
+  onRun: () => Promise<void>
+}
+
+/**
+ * Owns one bounded poll loop.
+ *
+ * Guarantees: at most one task runs at a time (a scheduled tick whose turn
+ * arrives while a run is in flight is dropped); consecutive failures double
+ * the delay up to maxBackoffMs and reset on the first success; the loop
+ * stops forever at deadlineMs and cancels its timer.
+ */
+export class PollGuard {
+  private readonly options: Required<PollGuardOptions>
+  private handle: unknown
+  private running = false
+  private startedAt = 0
+  private stopped = false
+  private failures = 0
+
+  /** @param options - loop bounds; interval/deadline/backoff/onRun are required, the rest optional. */
+  constructor(options: PollGuardOptions) {
+    this.options = {
+      timers: DEFAULT_TIMERS,
+      onDeadline: () => {},
+      onSettled: () => {},
+      ...options,
+    }
+  }
+
+  /** Start the loop. Safe to call once; later calls are ignored. */
+  start(): void {
+    if (this.startedAt !== 0) return
+    this.startedAt = Date.now()
+    this.schedule(this.options.intervalMs)
+  }
+
+  /** Stop the loop permanently and drop any pending tick. */
+  stop(): void {
+    this.stopped = true
+    this.options.timers.clear(this.handle)
+    this.handle = undefined
+  }
+
+  private schedule(delayMs: number): void {
+    if (this.stopped) return
+    this.handle = this.options.timers.set(() => { void this.tick() }, delayMs)
+  }
+
+  private delay(): number {
+    const backoff = this.options.intervalMs * 2 ** Math.min(this.failures, 8)
+    return Math.min(backoff, this.options.maxBackoffMs)
+  }
+
+  private async tick(): Promise<void> {
+    if (this.stopped) return
+    if (this.running) return // Anti-overlap: drop ticks that arrive mid-run.
+    if (Date.now() - this.startedAt >= this.options.deadlineMs) {
+      this.stopped = true
+      this.options.onDeadline()
+      return
+    }
+    this.running = true
+    try {
+      await this.options.onRun()
+      this.failures = 0
+    } catch {
+      this.failures += 1
+    } finally {
+      this.running = false
+      this.options.onSettled(this.failures)
+      this.schedule(this.delay())
+    }
+  }
+}