dsh-plugin-jules 0.1.0

package/lib/watch.js

@@ -0,0 +1,387 @@
+/**
+ * Background watching for Jules sessions.
+ *
+ * A Jules session runs for minutes in Google's cloud, so a turn that blocks on
+ * one wastes the model's time. `jules_watch` instead registers the wait with
+ * `ctx.jobs`: the call returns a job id immediately, the harness keeps polling
+ * out of band, and `dsh-tool-jobs` delivers a completion notice to the owning
+ * agent when the session finishes, fails, or stops to ask something. The model
+ * reads the report with `job_output` on a later step.
+ *
+ * The session state alone is not a completion signal. Jules can post its final
+ * answer as an `agentMessaged` activity and then leave `state` sitting at
+ * `IN_PROGRESS` indefinitely, so the watcher treats the append-only activity
+ * log as authoritative and settles on what the agent did, not only on what the
+ * state field says.
+ *
+ * @module dsh-plugin-jules/watch
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { sleep } from "./async.js";
+import { JulesError, JulesNotFoundError } from "./client.js";
+import { DEFAULT_WAIT_STATES, needsAttentionState, sessionIdOf, settledState } from "./types.js";
+import { renderWait, sessionDetail } from "./views.js";
+/** Attempts allowed for a read that may race session creation. */
+const VISIBILITY_ATTEMPTS = 4;
+/**
+ * First delay between visibility attempts, in milliseconds. The wait is short
+ * on purpose: the race resolves in about a second in practice, and this same
+ * bound is what a genuinely bad session id costs before it reports.
+ */
+const VISIBILITY_DELAY_MS = 500;
+/**
+ * Read something that may not be visible yet.
+ *
+ * A session created moments ago answers `Requested entity was not found` for its
+ * first read: Jules mints the id before the resource is queryable, which is why
+ * the official SDK retries the first request on a 404. Only a not-found is
+ * retried, and only while it keeps saying so — a genuinely bad id still reports
+ * once the attempts are spent.
+ * @param operation - the read to attempt.
+ * @param signal - task-owned cancellation signal.
+ * @returns the operation's result.
+ * @throws the last failure once the attempts are exhausted, or any other error at once.
+ */
+async function readWhenVisible(operation, signal) {
+    let lastError;
+    for (let attempt = 1; attempt <= VISIBILITY_ATTEMPTS; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!(error instanceof JulesNotFoundError))
+                throw error;
+            lastError = error;
+            if (attempt === VISIBILITY_ATTEMPTS)
+                break;
+            await sleep(VISIBILITY_DELAY_MS * attempt, signal);
+        }
+    }
+    throw lastError;
+}
+/**
+ * Stable identity of one activity, for de-duplicating a re-read page.
+ * @param activity - one activity from the log.
+ * @returns a key that is stable across reads of the same activity.
+ */
+function activityKey(activity) {
+    return activity.id ?? activity.name ?? `${activity.createTime ?? ''}:${activity.originator ?? ''}`;
+}
+/**
+ * Read one page without re-recording what an earlier page already produced.
+ * @param collected - the running log for this watch, appended in place.
+ * @param seen - identities already recorded.
+ * @param page - the newest page from the service.
+ * @returns only the activities this watch had not seen before.
+ */
+function absorb(collected, seen, page) {
+    const fresh = [];
+    for (const activity of page) {
+        const key = activityKey(activity);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        collected.push(activity);
+        fresh.push(activity);
+    }
+    return fresh;
+}
+/**
+ * The newest `createTime` in a set of activities, used as the next cursor.
+ * @param activities - activities already collected.
+ * @returns the newest timestamp, or undefined when none carries one.
+ */
+function newestTime(activities) {
+    let newest;
+    for (const activity of activities) {
+        const time = activity.createTime;
+        if (time !== undefined && (newest === undefined || time > newest))
+            newest = time;
+    }
+    return newest;
+}
+/**
+ * Poll one session until the agent hands something back, then describe it.
+ *
+ * Separated from the job adapter so the settling rules — which states end a
+ * watch, which activities end it, when the budget expires, and what the report
+ * contains — are testable without a live agent owner or a real job registry.
+ * @param client - the configured Jules client.
+ * @param session - bare session id.
+ * @param targets - states that end the watch.
+ * @param budgetMs - total watch budget.
+ * @param config - polling rules.
+ * @param signal - task-owned cancellation signal.
+ * @returns why the watch stopped and the rendered report.
+ * @throws whatever the client throws, including cancellation.
+ */
+export async function runWatch(client, session, targets, budgetMs, config, signal) {
+    const started = Date.now();
+    let polls = 0;
+    let trigger = 'state';
+    // One cursor over an append-only log: the first read establishes it and each
+    // later poll asks only for what is new. The cursor is a bandwidth
+    // optimisation, so identity de-duplication carries correctness on its own —
+    // a rejected or ignored cursor costs requests, never a wrong answer.
+    const collected = [];
+    const seen = new Set();
+    absorb(collected, seen, await readWhenVisible(() => client.listAllActivities(session, {
+        signal,
+        maxPages: config.maxActivityPages,
+        pageSize: 100,
+    }), signal));
+    let cursor = newestTime(collected);
+    let cursorUsable = true;
+    let current = await readWhenVisible(() => client.getSession(session, signal), signal);
+    polls += 1;
+    let previousState = current.state ?? 'STATE_UNSPECIFIED';
+    // Only what happens after the watch starts is news. The baseline is kept for
+    // the report but never settles the watch on its own: the caller who just
+    // answered the agent's question does not need it reported back.
+    let fresh = [];
+    for (;;) {
+        const state = current.state ?? 'STATE_UNSPECIFIED';
+        // Terminal means nothing more will ever arrive, so report it at once even
+        // when the watch started after the fact.
+        if (settledState(state)) {
+            trigger = 'state';
+            break;
+        }
+        // An attention state settles the watch only when the session moved into it.
+        // Settling on the state it started in would make the ordinary
+        // "answer the agent, then watch for its reply" flow return instantly on the
+        // stale pre-answer state, which is no news at all.
+        if (targets.has(state) && state !== previousState) {
+            trigger = 'state';
+            break;
+        }
+        // Terminal activities outrank everything: the log is the authority for what
+        // actually happened, and a failed session must never wait out its budget.
+        if (collected.some(activity => activity.sessionFailed !== undefined)) {
+            trigger = 'failed';
+            break;
+        }
+        if (collected.some(activity => activity.sessionCompleted !== undefined)) {
+            trigger = 'completed';
+            break;
+        }
+        // A message posted since the watch began: the agent has handed something
+        // back, whether a question or a finished report, and may leave `state`
+        // reading IN_PROGRESS while it waits.
+        if (config.settleOnMessage && fresh.some(activity => activity.agentMessaged !== undefined)) {
+            trigger = 'message';
+            break;
+        }
+        const elapsed = Date.now() - started;
+        if (elapsed >= budgetMs) {
+            trigger = 'timeout';
+            break;
+        }
+        // Never oversleep past the deadline: a long poll interval must not turn a
+        // short budget into a much longer watch.
+        previousState = state;
+        await sleep(Math.min(config.pollIntervalMs, Math.max(250, budgetMs - elapsed)), signal);
+        current = await client.getSession(session, signal);
+        polls += 1;
+        let page;
+        try {
+            page = await client.listActivities(session, {
+                signal,
+                pageSize: 100,
+                ...cursorUsable && cursor !== undefined ? { since: cursor } : {},
+            });
+        }
+        catch (error) {
+            // The cursor form is not in the API reference — the documented
+            // `?createTime=` parameter is rejected outright — so a 400 here means this
+            // deployment does not take the filter either. Drop the cursor rather than
+            // the watch: de-duplication already makes correctness independent of it.
+            if (!cursorUsable || !(error instanceof JulesError) || error.status !== 400)
+                throw error;
+            cursorUsable = false;
+            page = await client.listActivities(session, { signal, pageSize: 100 });
+        }
+        fresh = absorb(collected, seen, page.activities ?? []);
+        cursor = newestTime(collected) ?? cursor;
+    }
+    const detail = sessionDetail(current, collected);
+    const waitedMs = Date.now() - started;
+    const wait = {
+        id: detail.id,
+        title: detail.title,
+        state: detail.state,
+        url: detail.url,
+        settled: settledState(detail.state),
+        timedOut: trigger === 'timeout',
+        needsAttention: needsAttentionState(detail.state),
+        waitedMs,
+        polls,
+        planId: detail.planId,
+        planSteps: detail.planSteps,
+        pullRequests: detail.pullRequests,
+        lastMessage: detail.lastMessage,
+        lastProgress: detail.lastProgress,
+    };
+    return {
+        trigger,
+        detail: describeWatch(trigger, detail.state, waitedMs),
+        report: renderWait(wait),
+        wait,
+    };
+}
+/**
+ * One short phrase describing why a watch stopped, for the job status line.
+ * @param trigger - why the watch stopped.
+ * @param state - the session state at settle time.
+ * @param waitedMs - how long the watch ran.
+ * @returns the status detail.
+ */
+function describeWatch(trigger, state, waitedMs) {
+    const seconds = Math.round(waitedMs / 1000);
+    if (trigger === 'timeout')
+        return `still ${state} after ${seconds}s`;
+    if (trigger === 'failed')
+        return `session failed (${state})`;
+    if (trigger === 'completed')
+        return `session completed (${state})`;
+    // "checkpoint" not "finished": an agent message means the floor is the
+    // caller's, and the session may well keep going once they answer.
+    if (trigger === 'message')
+        return `checkpoint: agent message (${state})`;
+    return `session ${state}`;
+}
+/**
+ * Register `jules_watch`.
+ *
+ * Registered through `ctx.inject(['jobs'])` rather than a plugin-level
+ * injection, so a composition without the job registry still gets the rest of
+ * the tool family instead of holding the whole plugin pending forever.
+ * @param ctx - plugin context supplying the job registry.
+ * @param client - the configured Jules client.
+ * @param config - watch budgets and polling bounds.
+ * @param journal - durable record of armed watches, when storage is mounted.
+ */
+export function registerJulesWatch(ctx, client, config, journal, live) {
+    ctx.tools.register(defineTool({
+        name: 'jules_watch',
+        description: 'Watch a Jules session in the background — this is how you wait for one. Returns a job id immediately and notifies '
+            + 'you when the session completes, fails, needs a plan decision, or the agent posts a message; read the report with job_output. '
+            + 'Call it once, then END YOUR TURN and do other work. Do not poll jules_status alongside it: the notice is the signal, and nothing '
+            + 'you check in the meantime will have changed.',
+        parameters: {
+            session: { type: 'string', required: true, description: 'Session id, "sessions/<id>", or the session URL.' },
+            timeoutMs: {
+                type: 'number',
+                description: 'How long to keep watching before giving up, in milliseconds. '
+                    + 'Defaults to the configured watchDefaultMs and is capped by watchMaxMs.',
+            },
+            until: {
+                type: 'array',
+                description: 'Session states that end the watch. Defaults to completion, failure, a pending plan, and a question.',
+                items: { type: 'string' },
+            },
+        },
+        output: {
+            schema: {
+                type: 'object', additionalProperties: false,
+                properties: {
+                    kind: { type: 'string', required: true, const: 'background' },
+                    jobId: { type: 'string', required: true },
+                },
+            },
+            render: (args, value) => [{
+                    type: 'text',
+                    text: `Watching Jules session ${args.session} in the background as job ${value.jobId}. `
+                        + 'You will be notified when it finishes or needs you; read the report with job_output. '
+                        + 'Do not poll it; continue with other work.',
+                }],
+        },
+        // Read-only against the service: it registers local work and asks Jules for
+        // nothing new, so watching several sessions in one turn may overlap.
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+            const owner = exec.agent;
+            if (owner === undefined) {
+                throw new Error('jules_watch requires an agent Session, because the completion notice is delivered to the session that started the watch');
+            }
+            const session = sessionIdOf(args.session);
+            const requested = args.timeoutMs ?? config.defaultMs;
+            // Floored at 30s: a watch shorter than the poll interval cannot observe
+            // anything, so a caller asking for one would pay for a job that reports
+            // only the state it already had. Ceilinged by config so a caller cannot
+            // pin a poller on this machine indefinitely.
+            const budget = Math.max(30_000, Math.min(Math.trunc(requested), config.maxMs));
+            const targets = new Set(args.until === undefined || args.until.length === 0 ? DEFAULT_WAIT_STATES : args.until);
+            const jobId = startWatchJob(ctx, client, owner, session, targets, budget, config, journal, live);
+            return { kind: 'background', jobId: String(jobId) };
+        },
+    }));
+}
+/**
+ * Start the polling job and return its id.
+ *
+ * The controller is task-owned rather than the tool call's: once the job id is
+ * published the model is tracking that work, so a later cancellation of the
+ * originating call must not silently kill it. `job_kill`, owner disposal,
+ * and service teardown own this lifetime instead.
+ * @param ctx - plugin context supplying the job registry.
+ * @param client - the configured Jules client.
+ * @param owner - the agent that receives the completion notice.
+ * @param session - bare session id.
+ * @param targets - states that end the watch.
+ * @param budgetMs - total watch budget.
+ * @param config - polling bounds.
+ * @returns the registry-issued job id.
+ */
+function startWatchJob(ctx, client, owner, session, targets, budgetMs, config, journal, live) {
+    const controller = new AbortController();
+    let cancelled = false;
+    let settle = () => { };
+    const done = new Promise((resolve) => { settle = resolve; });
+    const watch = async () => {
+        try {
+            const outcome = await runWatch(client, session, targets, budgetMs, config, controller.signal);
+            // The watch itself succeeded. A failed or waiting *session* is reported in
+            // the detail and the report, not as a broken job.
+            settle({ status: 'completed', detail: outcome.detail, output: outcome.report });
+            // It reached its own conclusion, so the journal has nothing left to
+            // report. A kill or a teardown deliberately does NOT release: a teardown
+            // is precisely the restart this journal exists to survive.
+            live.delete(session);
+            void journal()?.release(session);
+        }
+        catch (error) {
+            if (cancelled) {
+                settle({ status: 'killed', detail: 'watch cancelled' });
+                return;
+            }
+            settle({ status: 'failed', detail: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    const jobId = ctx.jobs.start({
+        kind: 'jules',
+        label: `session ${session}`,
+        owner,
+        run: () => {
+            void watch();
+            return {
+                cancel: (reason) => {
+                    if (cancelled)
+                        return;
+                    cancelled = true;
+                    controller.abort(new Error(reason ?? 'watch cancelled'));
+                },
+                done,
+            };
+        },
+    });
+    // Recorded only once the registry has accepted the job, so a refusal at the
+    // concurrency cap leaves no phantom entry behind.
+    const opened = journal();
+    if (opened !== undefined) {
+        const armedAt = Date.now();
+        live.add(session);
+        void opened.arm({ session, startedAt: armedAt, expiresAt: armedAt + budgetMs });
+    }
+    return jobId;
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "dsh-plugin-jules",
+  "version": "0.1.0",
+  "description": "Google Jules remote coding agent integration for DeepSeek Harness",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "jules",
+    "google-jules",
+    "coding-agent",
+    "remote-agent"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Aurimas Šeputis"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rbviz/dsh-plugin-jules.git"
+  },
+  "homepage": "https://github.com/rbviz/dsh-plugin-jules#readme",
+  "bugs": {
+    "url": "https://github.com/rbviz/dsh-plugin-jules/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-credentials": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-jobs": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-credentials": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-jobs": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "zod": "^4.4.3",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/dsh-jobs-local": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-storage": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-storage-json": "^0.1.5-rc.2",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "node scripts/build.mjs --noEmit",
+    "link-dsh-deps": "node scripts/link-dsh-deps.mjs",
+    "test": "node scripts/build.mjs && node --test test/*.test.mjs"
+  }
+}

package/scripts/build.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * Compile the plugin with the TypeScript that the running dsh installation
+ * already ships, so this package needs no toolchain of its own.
+ *
+ * Resolution order: `$DSH_TSC`, then a `typescript` found through this
+ * package's own `node_modules` (populated by `link-dsh-deps`), then the
+ * harness home. Run `npm run link-dsh-deps` first if this fails.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+function candidateTsc() {
+  if (process.env.DSH_TSC !== undefined && existsSync(process.env.DSH_TSC)) return process.env.DSH_TSC
+  const home = process.env.DSH_HOME ?? join(process.env.HOME ?? '', '.dsh')
+  return [
+    join(PACKAGE_ROOT, 'node_modules', 'typescript', 'bin', 'tsc'),
+    join(home, 'profiles', 'node_modules', 'typescript', 'bin', 'tsc'),
+  ].find(existsSync)
+}
+
+const tsc = candidateTsc()
+if (tsc === undefined) {
+  process.stderr.write('build: no typescript found; run "npm run link-dsh-deps" or set DSH_TSC\n')
+  process.exit(1)
+}
+
+const result = spawnSync(process.execPath, [tsc, '-p', join(PACKAGE_ROOT, 'tsconfig.json'), ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  cwd: PACKAGE_ROOT,
+})
+process.exit(result.status ?? 1)

package/scripts/link-dsh-deps.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Make the in-box `@deepseek-ai/*` packages importable from this plugin's own
+ * directory.
+ *
+ * Why this exists: a profile installs an out-of-tree bundle with pnpm's
+ * `link:` protocol, which puts a symlink in the profile's `node_modules` but
+ * creates no `node_modules` beside the real package. Node resolves a symlinked
+ * package to its realpath, so this plugin's own `import '@deepseek-ai/dsh-tools'`
+ * would otherwise fail with ERR_MODULE_NOT_FOUND even though dsh itself loaded
+ * the file.
+ *
+ * The fix is to point each declared peer dependency at the copy the running
+ * installation already uses, so both sides share one module instance. dsh
+ * maintains exactly such a directory at `$DSH_HOME/profiles/node_modules`
+ * (its "module fallback"), whose entries are themselves links into the
+ * installation.
+ *
+ * Usage:
+ *   node scripts/link-dsh-deps.mjs [--home <dsh home>] [--check]
+ *
+ * `--check` reports what is missing without writing anything.
+ */
+
+import {
+  existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, unlinkSync,
+} from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const MANIFEST = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'))
+
+/**
+ * Every name to link: runtime peers plus the loader packages the composition
+ * test boots. Types alone still need resolution, so this is not filtered.
+ */
+const REQUIRED = [...new Set([
+  ...Object.keys(MANIFEST.peerDependencies ?? {}),
+  ...Object.keys(MANIFEST.devDependencies ?? {}),
+])]
+
+function parseArgs(argv) {
+  const options = { home: process.env.DSH_HOME, check: false, optional: false }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--check') options.check = true
+    else if (arg === '--optional') options.optional = true
+    else if (arg === '--home') options.home = argv[++index]
+    else if (arg.startsWith('--home=')) options.home = arg.slice('--home='.length)
+    else {
+      process.stderr.write(`link-dsh-deps: unknown argument ${arg}\n`)
+      process.exit(2)
+    }
+  }
+  if (options.home === undefined || options.home.length === 0) options.home = join(homedir(), '.dsh')
+  return { home: resolve(options.home), check: options.check, optional: options.optional }
+}
+
+function homedir() {
+  return process.env.HOME ?? process.env.USERPROFILE ?? ''
+}
+
+/** `node_modules` directories that may hold the in-box packages, best candidate first. */
+function candidateRoots(home) {
+  const roots = [join(home, 'profiles', 'node_modules')]
+  const profiles = join(home, 'profiles')
+  if (existsSync(profiles)) {
+    for (const entry of readdirSync(profiles, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name === 'node_modules') continue
+      roots.push(join(profiles, entry.name, 'node_modules'))
+    }
+  }
+  return roots
+}
+
+/** First existing directory providing `packageName`, or undefined. */
+function locate(packageName, roots) {
+  for (const root of roots) {
+    const candidate = join(root, packageName)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+  }
+  return undefined
+}
+
+const { home, check, optional } = parseArgs(process.argv.slice(2))
+const roots = candidateRoots(home)
+const target = join(PACKAGE_ROOT, 'node_modules')
+const missing = []
+
+for (const packageName of REQUIRED) {
+  const source = locate(packageName, roots)
+  if (source === undefined) {
+    missing.push(packageName)
+    continue
+  }
+  const link = join(target, packageName)
+  const current = existsSync(link)
+    ? (() => { try { return readlinkSync(link) } catch { return undefined } })()
+    : undefined
+  if (current === resolve(source)) continue
+  if (check) {
+    process.stdout.write(`would link ${packageName} -> ${source}\n`)
+    continue
+  }
+  mkdirSync(dirname(link), { recursive: true })
+  // rmSync, not unlinkSync: these peers are devDependencies too, so npm may have
+  // installed them as real directories. unlinkSync on one throws EISDIR, and
+  // swallowing that left the symlink to fail with EEXIST against a directory
+  // that was still there — which is exactly how this broke the first time a
+  // checkout had both an npm install and a local harness.
+  rmSync(link, { recursive: true, force: true })
+  symlinkSync(resolve(source), link, 'junction')
+  process.stdout.write(`linked ${packageName} -> ${source}\n`)
+}
+
+if (missing.length > 0) {
+  const detail = `link-dsh-deps: could not find ${missing.join(', ')}\n`
+    + `  searched:\n${roots.map(root => `    ${root}\n`).join('')}`
+    + '  pass --home <dsh home> or set DSH_HOME to the harness home that installed them.\n'
+  // --optional is for a machine with no harness installed: CI, or a consumer
+  // building from a tarball. The packages then come from node_modules like any
+  // other dependency, so the absence of a harness home is not a failure.
+  if (optional) {
+    process.stderr.write(detail + '  (--optional: continuing; node_modules will be used as-is)\n')
+    process.exit(0)
+  }
+  process.stderr.write(detail)
+  process.exit(1)
+}
+
+if (check) process.stdout.write('link-dsh-deps: all peer dependencies resolve\n')