@delegoapp/runner 0.1.0

package/dist/git/command.js

@@ -0,0 +1,33 @@
+import { spawn } from 'node:child_process';
+export const maxCapturedOutputBytes = 64_000;
+export function appendBoundedOutput(current, chunk) {
+    const next = current + chunk.toString('utf8');
+    if (Buffer.byteLength(next, 'utf8') <= maxCapturedOutputBytes) {
+        return next;
+    }
+    return next.slice(-maxCapturedOutputBytes);
+}
+export function runCommand(command, args, cwd) {
+    return new Promise((resolveCommand, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            env: {
+                ...process.env,
+                GIT_TERMINAL_PROMPT: '0',
+            },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout = appendBoundedOutput(stdout, chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr = appendBoundedOutput(stderr, chunk);
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            resolveCommand({ code, stdout, stderr });
+        });
+    });
+}

package/dist/git/commit.js

@@ -0,0 +1,82 @@
+import { runCommand } from './command.js';
+import { changedFilePaths } from './workspace.js';
+async function readGitValue(path, args) {
+    const result = await runCommand('git', args, path);
+    if (result.code !== 0) {
+        throw new Error(`Unable to read git value (${args.join(' ')}): ${result.stderr || result.stdout || 'unknown git error'}`);
+    }
+    return result.stdout.trim();
+}
+async function ensureGitCommitIdentity(path) {
+    const [name, email] = await Promise.all([
+        runCommand('git', ['config', 'user.name'], path),
+        runCommand('git', ['config', 'user.email'], path),
+    ]);
+    if (name.code !== 0 || !name.stdout.trim()) {
+        const setName = await runCommand('git', ['config', 'user.name', 'Delego Runner'], path);
+        if (setName.code !== 0) {
+            throw new Error(`Unable to configure git user.name: ${setName.stderr || setName.stdout || 'unknown git error'}`);
+        }
+    }
+    if (email.code !== 0 || !email.stdout.trim()) {
+        const setEmail = await runCommand('git', ['config', 'user.email', 'runner@delego.local'], path);
+        if (setEmail.code !== 0) {
+            throw new Error(`Unable to configure git user.email: ${setEmail.stderr || setEmail.stdout || 'unknown git error'}`);
+        }
+    }
+}
+export function commitSubjectForJob(job) {
+    const title = job.linearIssue.title
+        ?.replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 120);
+    return title
+        ? `${job.linearIssue.identifier}: ${title}`
+        : `${job.linearIssue.identifier}: apply delegated changes`;
+}
+function commitBodyForJob(job, changedFiles) {
+    return [
+        `Linear issue: ${job.linearIssue.identifier}`,
+        job.linearIssue.url ? `Linear URL: ${job.linearIssue.url}` : null,
+        '',
+        'Delegated through Delego local runner.',
+        '',
+        'Changed files:',
+        ...changedFiles.slice(0, 50).map((file) => `- ${file}`),
+    ]
+        .filter((part) => part !== null)
+        .join('\n');
+}
+export async function createLocalCommit(repositoryPath, job, branchName, statusLines) {
+    const changedFiles = changedFilePaths(statusLines);
+    if (changedFiles.length === 0) {
+        throw new Error('Refusing to create an empty commit because no repository changes were detected.');
+    }
+    await ensureGitCommitIdentity(repositoryPath);
+    const add = await runCommand('git', ['add', '--all'], repositoryPath);
+    if (add.code !== 0) {
+        throw new Error(`Unable to stage repository changes: ${add.stderr || add.stdout || 'unknown git error'}`);
+    }
+    const subject = commitSubjectForJob(job);
+    const commit = await runCommand('git', ['commit', '-m', subject, '-m', commitBodyForJob(job, changedFiles)], repositoryPath);
+    if (commit.code !== 0) {
+        throw new Error(`Unable to create local commit: ${commit.stderr || commit.stdout || 'unknown git error'}`);
+    }
+    const [sha, authorName, authorEmail, committedAt] = await Promise.all([
+        readGitValue(repositoryPath, ['rev-parse', 'HEAD']),
+        readGitValue(repositoryPath, ['show', '-s', '--format=%an', 'HEAD']),
+        readGitValue(repositoryPath, ['show', '-s', '--format=%ae', 'HEAD']),
+        readGitValue(repositoryPath, ['show', '-s', '--format=%cI', 'HEAD']),
+    ]);
+    return {
+        sha,
+        shortSha: sha.slice(0, 12),
+        subject,
+        branchName,
+        authorName,
+        authorEmail,
+        committedAt,
+        changedFileCount: changedFiles.length,
+        changedFiles,
+    };
+}

package/dist/git/publish.js

@@ -0,0 +1,70 @@
+import { validatePublishingPolicy } from '../config.js';
+import { runCommand } from './command.js';
+import { commitSubjectForJob } from './commit.js';
+function prTitleForJob(job) {
+    return commitSubjectForJob(job);
+}
+function prBodyForJob(job, commit) {
+    return [
+        `Linear issue: ${job.linearIssue.identifier}`,
+        job.linearIssue.url ? `Linear URL: ${job.linearIssue.url}` : null,
+        '',
+        `Local commit: ${commit.shortSha}`,
+        '',
+        'Created by Delego local runner.',
+    ]
+        .filter((part) => part !== null)
+        .join('\n');
+}
+function parsePrNumberFromUrl(url) {
+    const value = Number(url.match(/\/pull\/(\d+)(?:\b|$)/)?.[1]);
+    return Number.isFinite(value) ? value : null;
+}
+export async function publishBranchAndMaybePr(repositoryPath, job, branchName, commit) {
+    validatePublishingPolicy(job.publishingPolicy);
+    if (!job.publishingPolicy.autoPush) {
+        return null;
+    }
+    const push = await runCommand('git', ['push', '-u', 'origin', branchName], repositoryPath);
+    if (push.code !== 0) {
+        throw new Error(`Unable to push branch ${branchName}: ${push.stderr || push.stdout || 'unknown git error'}`);
+    }
+    if (!job.publishingPolicy.autoCreatePr) {
+        return null;
+    }
+    const title = prTitleForJob(job);
+    const args = [
+        'pr',
+        'create',
+        '--title',
+        title,
+        '--body',
+        prBodyForJob(job, commit),
+        '--head',
+        branchName,
+    ];
+    if (job.publishingPolicy.prDraft) {
+        args.push('--draft');
+    }
+    const pr = await runCommand('gh', args, repositoryPath);
+    if (pr.code !== 0) {
+        throw new Error(`Unable to create GitHub pull request: ${pr.stderr || pr.stdout || 'unknown gh error'}`);
+    }
+    const url = pr.stdout
+        .trim()
+        .split(/\r?\n/)
+        .find((line) => /^https?:\/\//.test(line.trim()))
+        ?.trim();
+    if (!url) {
+        throw new Error('GitHub CLI did not return a pull request URL.');
+    }
+    return {
+        url,
+        number: parsePrNumberFromUrl(url),
+        title,
+        branchName,
+        draft: job.publishingPolicy.prDraft,
+        repositorySlug: job.repositorySlug,
+        pushed: true,
+    };
+}

package/dist/git/workspace.js

@@ -0,0 +1,213 @@
+import { runCommand } from './command.js';
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+async function assertGitRepository(path) {
+    const result = await runCommand('git', ['rev-parse', '--show-toplevel'], path);
+    if (result.code !== 0) {
+        throw new Error(`Workspace is not a git repository: ${path}`);
+    }
+}
+async function isDirty(path) {
+    const result = await runCommand('git', ['status', '--porcelain'], path);
+    if (result.code !== 0) {
+        throw new Error(`Unable to inspect git status: ${result.stderr || result.stdout || 'unknown git error'}`);
+    }
+    return result.stdout.trim().length > 0;
+}
+export async function changedFiles(path) {
+    const result = await runCommand('git', ['status', '--porcelain'], path);
+    if (result.code !== 0) {
+        throw new Error(`Unable to inspect git changes: ${result.stderr || result.stdout || 'unknown git error'}`);
+    }
+    return result.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+function filePathFromPorcelainLine(line) {
+    const value = line.slice(3).trim();
+    const renameIndex = value.indexOf(' -> ');
+    return renameIndex === -1 ? value : value.slice(renameIndex + 4);
+}
+export function changedFilePaths(statusLines) {
+    return statusLines.map(filePathFromPorcelainLine).filter(Boolean);
+}
+function candidateRepositoryPaths(workspaceRoot, repositorySlug) {
+    const [owner, repo] = repositorySlug.split('/');
+    if (!owner || !repo) {
+        return [workspaceRoot];
+    }
+    return [
+        join(workspaceRoot, owner, repo),
+        join(workspaceRoot, repo),
+        workspaceRoot,
+    ];
+}
+async function remoteMatchesRepository(path, repositorySlug) {
+    const result = await runCommand('git', ['remote', 'get-url', 'origin'], path);
+    if (result.code !== 0) {
+        return false;
+    }
+    const normalized = result.stdout
+        .trim()
+        .replace(/\.git$/, '')
+        .toLowerCase();
+    return normalized.endsWith(`/${repositorySlug.toLowerCase()}`);
+}
+export async function resolveRepositoryPath(workspaceRoot, repositorySlug) {
+    for (const candidate of candidateRepositoryPaths(workspaceRoot, repositorySlug)) {
+        if (!existsSync(candidate)) {
+            continue;
+        }
+        try {
+            await assertGitRepository(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (candidate !== workspaceRoot ||
+            (await remoteMatchesRepository(candidate, repositorySlug))) {
+            console.log(`repository: using existing checkout ${candidate}`);
+            return candidate;
+        }
+    }
+    throw new Error(`No local checkout found for ${repositorySlug} under ${workspaceRoot}.`);
+}
+export function cachedSourceRepositoryPath(workspaceRoot, repositorySlug) {
+    const [owner, repo] = repositorySlug.split('/');
+    if (!owner || !repo) {
+        throw new Error(`Invalid repository slug: ${repositorySlug}`);
+    }
+    return join(workspaceRoot, 'sources', owner, `${repo}.git`);
+}
+async function assertBareGitRepository(path, cwd) {
+    const result = await runCommand('git', ['--git-dir', path, 'rev-parse', '--is-bare-repository'], cwd);
+    if (result.code !== 0 || result.stdout.trim() !== 'true') {
+        throw new Error(`Source cache is not a bare git repository: ${path}`);
+    }
+}
+export function jobWorktreePath(workspaceRoot, job) {
+    const [owner, repo] = job.repositorySlug.split('/');
+    if (!owner || !repo) {
+        throw new Error(`Invalid repository slug: ${job.repositorySlug}`);
+    }
+    return join(workspaceRoot, 'worktrees', owner, repo, job.id);
+}
+function repositoryCloneUrl(config, repositorySlug) {
+    if (config.gitCloneBaseUrl.endsWith(':')) {
+        return `${config.gitCloneBaseUrl}${repositorySlug}.git`;
+    }
+    return `${config.gitCloneBaseUrl}/${repositorySlug}.git`;
+}
+async function cloneBareSourceRepository(config, repositorySlug, target) {
+    let source = repositoryCloneUrl(config, repositorySlug);
+    try {
+        source = await resolveRepositoryPath(config.workspaceRoot, repositorySlug);
+        console.log(`repository: seeding bare source cache for ${repositorySlug} from ${source}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.log(`${message} Cloning bare source cache from ${source}.`);
+    }
+    const parent = join(target, '..');
+    mkdirSync(parent, { recursive: true });
+    const clone = await runCommand('git', ['clone', '--bare', source, target], config.workspaceRoot);
+    if (clone.code !== 0) {
+        throw new Error(`Unable to clone bare source cache for ${repositorySlug}: ${clone.stderr || clone.stdout || 'unknown git error'}`);
+    }
+    console.log(`repository: cached bare source for ${repositorySlug} at ${target}`);
+}
+async function resolveOrCloneSourceRepositoryPath(config, repositorySlug) {
+    mkdirSync(config.workspaceRoot, { recursive: true });
+    const sourceRepositoryPath = cachedSourceRepositoryPath(config.workspaceRoot, repositorySlug);
+    if (!existsSync(sourceRepositoryPath)) {
+        await cloneBareSourceRepository(config, repositorySlug, sourceRepositoryPath);
+    }
+    await assertBareGitRepository(sourceRepositoryPath, config.workspaceRoot);
+    return sourceRepositoryPath;
+}
+export function branchNameForJob(job) {
+    const issueKey = job.linearIssue.identifier
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    const suffix = job.id.slice(0, 8).toLowerCase();
+    return `delego/${issueKey || 'linear-issue'}-${suffix}`;
+}
+async function currentBranch(path) {
+    const result = await runCommand('git', ['rev-parse', '--abbrev-ref', 'HEAD'], path);
+    if (result.code !== 0) {
+        return null;
+    }
+    const branch = result.stdout.trim();
+    return branch ? branch : null;
+}
+async function branchExistsInBareRepo(sourceRepositoryPath, cwd, branchName) {
+    const result = await runCommand('git', [
+        '--git-dir',
+        sourceRepositoryPath,
+        'rev-parse',
+        '--verify',
+        '--quiet',
+        `refs/heads/${branchName}`,
+    ], cwd);
+    return result.code === 0;
+}
+export async function prepareWorkspace(config, job) {
+    const sourceRepositoryPath = await resolveOrCloneSourceRepositoryPath(config, job.repositorySlug);
+    const worktreePath = jobWorktreePath(config.workspaceRoot, job);
+    const branchName = branchNameForJob(job);
+    if (existsSync(worktreePath)) {
+        // Linear follow-up prompts on a terminal job restart the same job id, so the
+        // worktree from the previous run is already present. Reuse it when it's a
+        // valid checkout on the expected branch so the executor can continue the work.
+        try {
+            await assertGitRepository(worktreePath);
+            const head = await currentBranch(worktreePath);
+            if (head === branchName) {
+                console.log(`workspace: reusing ${worktreePath} on ${branchName}`);
+                return { sourceRepositoryPath, worktreePath, branchName };
+            }
+        }
+        catch {
+            // fall through to the preserve-for-inspection error below
+        }
+        throw new Error(`Job worktree already exists; preserving it for inspection at ${worktreePath}`);
+    }
+    mkdirSync(join(worktreePath, '..'), { recursive: true });
+    // Drop stale worktree records whose directories were removed off-disk so
+    // `git worktree add` doesn't refuse to check out the existing branch.
+    await runCommand('git', ['--git-dir', sourceRepositoryPath, 'worktree', 'prune'], config.workspaceRoot);
+    // If the branch already exists in the bare repo (e.g., the worktree from a
+    // prior run on this same job was deleted but the branch was kept), attach to
+    // it instead of trying to create a new branch.
+    const branchAlreadyExists = await branchExistsInBareRepo(sourceRepositoryPath, config.workspaceRoot, branchName);
+    const worktreeAddArgs = branchAlreadyExists
+        ? [
+            '--git-dir',
+            sourceRepositoryPath,
+            'worktree',
+            'add',
+            worktreePath,
+            branchName,
+        ]
+        : [
+            '--git-dir',
+            sourceRepositoryPath,
+            'worktree',
+            'add',
+            '-b',
+            branchName,
+            worktreePath,
+            'HEAD',
+        ];
+    const worktree = await runCommand('git', worktreeAddArgs, config.workspaceRoot);
+    if (worktree.code !== 0) {
+        throw new Error(`Unable to create worktree ${worktreePath}: ${worktree.stderr || worktree.stdout}`);
+    }
+    if (await isDirty(worktreePath)) {
+        throw new Error(`Prepared worktree has uncommitted changes; refusing to run in ${worktreePath}`);
+    }
+    console.log(`workspace: created ${worktreePath} from ${sourceRepositoryPath} on ${branchName}`);
+    return { sourceRepositoryPath, worktreePath, branchName };
+}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { readConfig, validatePublishingPolicy } from './config.js';
+export { normalizeExecutionPreferences } from './execution-prefs.js';
+export { ADAPTERS, ADAPTERS_BY_ID, claudeAdapter, codexAdapter, } from './executor/adapters/index.js';
+export { createLocalCommit } from './git/commit.js';
+export { branchNameForJob, cachedSourceRepositoryPath, jobWorktreePath, prepareWorkspace, } from './git/workspace.js';
+export { run, resolveRunnerConfig } from './run.js';

package/dist/job-pipeline.js

@@ -0,0 +1,164 @@
+import { validatePublishingPolicy } from './config.js';
+import { normalizeExecutionPreferences } from './execution-prefs.js';
+import { ADAPTERS_BY_ID } from './executor/adapters/index.js';
+import { runExecutor, summarizeExecutorFailure } from './executor/process.js';
+import { createLocalCommit } from './git/commit.js';
+import { publishBranchAndMaybePr, } from './git/publish.js';
+import { changedFilePaths, changedFiles, prepareWorkspace, } from './git/workspace.js';
+import { postJson, postRunnerEvent, reportCompletion, reportFailure, reportProgress, } from './relay-client.js';
+export async function pollOnce(config) {
+    const poll = await postJson(config, '/api/runner/jobs/poll', {
+        version: config.version,
+        supportedExecutors: config.supportedExecutors,
+    });
+    if (!poll.job) {
+        console.log(`poll: no job (${poll.reason ?? 'empty'})`);
+        return null;
+    }
+    return {
+        ...poll.job,
+        executionPreferences: normalizeExecutionPreferences(poll.job),
+    };
+}
+export async function runRealExecutionOnce(config) {
+    const job = await pollOnce(config);
+    if (!job) {
+        return false;
+    }
+    console.log(`claimed ${job.id} for ${job.repositorySlug}`);
+    await postRunnerEvent(config, '/api/runner/heartbeat', job.id);
+    let workspace = null;
+    let commitMetadata = null;
+    try {
+        validatePublishingPolicy(job.publishingPolicy);
+        workspace = await prepareWorkspace(config, job);
+        await reportProgress(config, job, `Prepared local workspace for ${job.executionPreferences.executor} execution.`, {
+            executor: job.executionPreferences.executor,
+            model: job.executionPreferences.model,
+            thinking: job.executionPreferences.thinking,
+            repositoryPath: workspace.worktreePath,
+            sourceRepositoryPath: workspace.sourceRepositoryPath,
+            worktreePath: workspace.worktreePath,
+            branchName: workspace.branchName,
+        });
+        const result = await runExecutor(config, job, workspace.worktreePath);
+        const changes = await changedFiles(workspace.worktreePath);
+        let prMetadata = null;
+        let pushed = false;
+        if (result.exitCode === 0 &&
+            !result.cancelled &&
+            !result.timedOut &&
+            changes.length > 0 &&
+            config.createCommit) {
+            commitMetadata = await createLocalCommit(workspace.worktreePath, job, workspace.branchName, changes);
+            console.log(`commit: created ${commitMetadata.shortSha} on ${workspace.branchName}`);
+            if (job.publishingPolicy.autoPush) {
+                await reportProgress(config, job, 'Publishing branch with local git credentials.', {
+                    branchName: workspace.branchName,
+                    repositorySlug: job.repositorySlug,
+                    publishingPolicy: job.publishingPolicy,
+                });
+                prMetadata = await publishBranchAndMaybePr(workspace.worktreePath, job, workspace.branchName, commitMetadata);
+                pushed = true;
+                if (prMetadata) {
+                    console.log(`publish: created ${prMetadata.draft ? 'draft ' : ''}PR ${prMetadata.url}`);
+                }
+                else {
+                    console.log(`publish: pushed ${workspace.branchName} without creating a PR`);
+                }
+            }
+        }
+        const remainingChanges = await changedFiles(workspace.worktreePath);
+        const metadata = {
+            attemptId: job.attemptId,
+            repositorySlug: job.repositorySlug,
+            branchName: workspace.branchName,
+            repositoryPath: workspace.worktreePath,
+            sourceRepositoryPath: workspace.sourceRepositoryPath,
+            worktreePath: workspace.worktreePath,
+            exitCode: result.exitCode,
+            signal: result.signal,
+            timedOut: result.timedOut,
+            cancelled: result.cancelled,
+            createCommit: config.createCommit,
+            executionPreferences: job.executionPreferences,
+            changedFileCount: changes.length,
+            changedFiles: changedFilePaths(changes).slice(0, 50),
+            remainingChangeCount: remainingChanges.length,
+            remainingChanges: changedFilePaths(remainingChanges).slice(0, 50),
+            commitMetadata,
+            prMetadata,
+            publishingPolicy: job.publishingPolicy,
+            pushed,
+            assistantResponse: result.finalReply,
+            stdoutTail: result.stdout,
+            stderrTail: result.stderr,
+        };
+        if (result.exitCode === 0 && !result.cancelled && !result.timedOut) {
+            const executorLabel = ADAPTERS_BY_ID[job.executionPreferences.executor].displayName;
+            if (changes.length === 0) {
+                await reportCompletion(config, job, `${executorLabel} executor completed successfully with no repository changes.`, metadata);
+                console.log(`complete: reported no-change success for ${job.id}`);
+                if (result.stdout.trim()) {
+                    console.log(`executor stdout tail:\n${result.stdout.trim()}`);
+                }
+                if (result.stderr.trim()) {
+                    console.log(`executor stderr tail:\n${result.stderr.trim()}`);
+                }
+            }
+            else {
+                const summary = prMetadata
+                    ? `${executorLabel} executor completed successfully and created pull request ${prMetadata.url}.`
+                    : commitMetadata
+                        ? job.publishingPolicy.autoPush
+                            ? `${executorLabel} executor completed successfully, created local commit ${commitMetadata.shortSha}, and pushed ${workspace.branchName}.`
+                            : `${executorLabel} executor completed successfully and created local commit ${commitMetadata.shortSha}; publishing is manual.`
+                        : `${executorLabel} executor completed successfully with ${changes.length} changed file(s); local commit creation is disabled.`;
+                await reportCompletion(config, job, summary, metadata);
+                console.log(`changes: ${changes.join(', ')}`);
+                console.log(`complete: reported success for ${job.id}`);
+            }
+        }
+        else {
+            const summary = summarizeExecutorFailure(result);
+            await reportFailure(config, job, summary, metadata, result.cancelled);
+            console.log(`terminal: reported ${result.cancelled ? 'cancellation' : 'failure'} for ${job.id}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        await reportFailure(config, job, message, {
+            attemptId: job.attemptId,
+            repositorySlug: job.repositorySlug,
+            branchName: workspace?.branchName,
+            repositoryPath: workspace?.worktreePath,
+            sourceRepositoryPath: workspace?.sourceRepositoryPath,
+            worktreePath: workspace?.worktreePath,
+            commitMetadata,
+            publishingPolicy: job.publishingPolicy,
+        });
+        console.error(`failed ${job.id}: ${message}`);
+    }
+    finally {
+        await postRunnerEvent(config, '/api/runner/heartbeat', null);
+    }
+    return true;
+}
+export async function runMockExecutionOnce(config) {
+    const job = await pollOnce(config);
+    if (!job) {
+        return;
+    }
+    console.log('claimed job request payload:');
+    console.log(JSON.stringify(job, null, 2));
+    await reportProgress(config, job, 'Mock runner received the queued job payload.', {
+        repositorySlug: job.repositorySlug,
+    });
+    console.log(`progress: reported for ${job.id}`);
+    await reportCompletion(config, job, 'Mock runner completed without touching git, workspaces, executors, or GitHub.', {
+        attemptId: job.attemptId,
+        mode: 'mock',
+    });
+    console.log(`complete: reported success for ${job.id}`);
+    await postRunnerEvent(config, '/api/runner/heartbeat', null);
+}

package/dist/pairing.js

@@ -0,0 +1,65 @@
+import { getProfile, readStore, upsertProfile, } from './credentials-store.js';
+function normalizeRelayUrl(value) {
+    return value.replace(/\/+$/, '');
+}
+export async function pairAndStore(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const now = input.now ?? (() => new Date());
+    const relayUrl = normalizeRelayUrl(input.relayUrl);
+    let store;
+    try {
+        store = readStore(input.credentialsPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            store = { version: 1, profiles: {} };
+        }
+        else {
+            throw error;
+        }
+    }
+    const existing = getProfile(store, input.profileName);
+    const orphanedRunnerId = existing?.runnerId ?? null;
+    let response;
+    try {
+        response = await fetchImpl(`${relayUrl}/api/runner/register`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${input.pairingToken}`,
+            },
+            body: JSON.stringify({
+                pairingToken: input.pairingToken,
+                version: input.version,
+                supportedExecutors: input.supportedExecutors,
+            }),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`delego-runner: unable to reach relay at ${relayUrl}/api/runner/register: ${message}`);
+    }
+    if (response.status === 401) {
+        throw new Error('delego-runner: pairing token expired or already used. Mint a new one in the dashboard and retry.');
+    }
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        throw new Error(`delego-runner: relay rejected pairing (HTTP ${response.status}): ${body.error ?? 'unknown'}`);
+    }
+    if (!body.runner?.id || !body.bearer) {
+        throw new Error(`delego-runner: relay returned an unexpected response shape (missing runner.id or bearer)`);
+    }
+    const profile = {
+        relayUrl,
+        runnerId: body.runner.id,
+        bearer: body.bearer,
+        pairedAt: now().toISOString(),
+    };
+    upsertProfile(input.credentialsPath, input.profileName, profile);
+    return {
+        runnerId: profile.runnerId,
+        bearer: profile.bearer,
+        relayUrl: profile.relayUrl,
+        orphanedRunnerId,
+    };
+}