dorfl 0.0.0 → 0.1.0

package/dist/work-on.js

@@ -0,0 +1,387 @@
+import { cpSync, existsSync, mkdirSync, rmSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { git, runAsync } from './git.js';
+import { performClaim } from './claim-cas.js';
+import { encodeRepoKey, ensureMirror, fetchMirrorMain, mirrorPath, } from './repo-mirror.js';
+import { defaultConfigPath, loadConfig, saveConfig, } from './config.js';
+import { brand } from './brand.js';
+import { workBranchRef } from './slug-namespace.js';
+const DEFAULT_ARBITER = 'origin';
+/** Raised for usage/environment errors (exit 1, outcome 'usage-error'). */
+class WorkOnUsageError extends Error {
+}
+/**
+ * Run the `work-on` ritual. Never throws for the expected lost/contended/refused
+ * cases — those are returned with the appropriate exit code and NO worktree.
+ * Usage/environment problems surface as exit 1.
+ */
+export async function performWorkOn(options) {
+    const note = options.note ?? (() => { });
+    try {
+        return await runWorkOn(options, note);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, outcome: 'usage-error', message };
+    }
+}
+async function runWorkOn(options, note) {
+    const slug = options.slug;
+    if (!slug) {
+        throw new WorkOnUsageError('missing <slug>. usage: dorfl work-on <slug> [--remote <r>]');
+    }
+    const env = options.env;
+    const workspacesDir = options.workspacesDir ?? join(homedir(), brand.workdirName);
+    // The human worktree root: configured value wins; otherwise prompt + save on
+    // first use (a sensible suggestion, NEVER a silent default; never under
+    // ~/.dorfl/).
+    const root = await resolveHumanWorktreesRoot(options, note);
+    // Resolve the arbiter URL + a CLAIM CONTEXT (a checkout with the arbiter
+    // remote where the CAS runs). The ONLY thing that differs between the two
+    // forms is the claim context's location; both fetch + branch off the fresh
+    // arbiter main, so the starting commit is identical.
+    const ctx = await resolveClaimContext({
+        slug,
+        remote: options.remote,
+        cwd: options.cwd,
+        arbiter: options.arbiter ?? DEFAULT_ARBITER,
+        workspacesDir,
+        env,
+        note,
+    });
+    try {
+        // Claim FIRST. On a lost/contended/refused claim, create NO worktree
+        // (clean failure, exactly like `claim`).
+        const claim = await performClaim({
+            slug,
+            cwd: ctx.claimCwd,
+            arbiter: ctx.claimArbiter,
+            env,
+            humanPath: true,
+            override: options.override,
+            note,
+        });
+        if (claim.exitCode !== 0) {
+            const outcome = claim.outcome === 'not-ready'
+                ? 'refused'
+                : claim.exitCode === 2
+                    ? 'lost'
+                    : claim.exitCode === 3
+                        ? 'contended'
+                        : 'usage-error';
+            return { exitCode: claim.exitCode, outcome, message: claim.message };
+        }
+        // The claim landed. Create the human worktree off the FRESHLY-FETCHED
+        // arbiter main (which now includes the claim move). We branch from the hub
+        // mirror's main so both forms share one branching primitive.
+        const created = createHumanWorktree({
+            slug,
+            root,
+            arbiterUrl: ctx.arbiterUrl,
+            workspacesDir,
+            env,
+        });
+        // Copy named gitignored files (copy, not symlink) so the project is
+        // runnable; print a security notice. Source resolved per mode.
+        const copied = copyGitignoredFiles({
+            copy: options.copy,
+            copyFrom: options.copyFrom,
+            remoteMode: ctx.remoteMode,
+            inRepoSource: options.cwd,
+            destDir: created.dir,
+            note,
+        });
+        const message = `Created worktree for '${slug}' at ${created.dir} (branch ${created.branch}).`;
+        note(message);
+        note(`To start working:  cd ${created.dir}`);
+        // `--agent` (task `agent-interactive-launch`): launch the configured harness
+        // INTERACTIVELY in the freshly-created worktree so the human can immediately
+        // drive the agent there. It is NOT a tracked job (decision #3): no record, no
+        // gate — it blocks in the foreground until the human exits, then control
+        // returns and they drive `complete`/`requeue`. The model/session are bound in
+        // the CLI's launcher closure (config lives there).
+        if (options.launchInteractive) {
+            note(`Launching the configured harness interactively in ${created.dir}.`);
+            options.launchInteractive({ slug, dir: created.dir, env });
+        }
+        return {
+            exitCode: 0,
+            outcome: 'created',
+            dir: created.dir,
+            branch: created.branch,
+            arbiterUrl: ctx.arbiterUrl,
+            startCommit: created.startCommit,
+            copied,
+            message,
+        };
+    }
+    finally {
+        ctx.cleanup();
+    }
+}
+/**
+ * Resolve where + how the claim CAS runs, per mode. The starting commit is
+ * guaranteed identical because the claim and the worktree both branch off the
+ * freshly-fetched arbiter main; only the claim context's LOCATION differs.
+ */
+async function resolveClaimContext(params) {
+    const { remote, cwd, arbiter, workspacesDir, env, note } = params;
+    if (remote === undefined || remote.trim() === '') {
+        // IN-REPO: infer the arbiter URL from the current repo; claim runs here.
+        if ((await gitSoft(['rev-parse', '--git-dir'], cwd, env)).status !== 0) {
+            throw new WorkOnUsageError('not inside a git repository (run inside a clone, or use the remote form: work-on --remote <r> <slug>)');
+        }
+        const url = await gitSoft(['remote', 'get-url', arbiter], cwd, env);
+        if (url.status !== 0) {
+            throw new WorkOnUsageError(`no git remote named '${arbiter}' (set one, or pass --arbiter)`);
+        }
+        return {
+            arbiterUrl: url.stdout.trim(),
+            claimCwd: cwd,
+            claimArbiter: arbiter,
+            remoteMode: false,
+            cleanup: () => { },
+        };
+    }
+    // REMOTE: ensure a hub mirror for <remote> (create if absent, like agents do)
+    // so the worktree can later branch off it. The claim itself needs a normal
+    // (non-bare) checkout with an `origin/main` tracking ref + a work tree to
+    // commit in, which a bare mirror does not provide — so the claim runs in a
+    // THROWAWAY clone of the arbiter URL (removed in cleanup either way).
+    //
+    // When the mirror already exists we refresh ONLY `main` (non-pruning): a
+    // pruning mirror-fetch here would delete the LOCAL-ONLY `work/<slug>` branches
+    // of other live human worktrees off this hub.
+    const hubPath = mirrorPath(workspacesDir, remote);
+    let mirrorUrl;
+    if (existsSync(hubPath)) {
+        mirrorUrl = ensureMirrorUrl(remote);
+        fetchMirrorMain(hubPath, env);
+        note(`Reusing hub mirror for ${mirrorUrl} at ${hubPath}.`);
+    }
+    else {
+        const created = ensureMirror({ url: remote, workspacesDir, env });
+        mirrorUrl = created.url;
+        note(`Created hub mirror for ${mirrorUrl} at ${created.path}.`);
+    }
+    const claimDir = join(workspacesDir, 'claim', `${encodeRepoKey(mirrorUrl).split('/').join('__')}__${params.slug}`);
+    rmSync(claimDir, { recursive: true, force: true });
+    mkdirSync(dirname(claimDir), { recursive: true });
+    // A lightweight clone whose `origin` IS the arbiter URL — the claim CAS fetches
+    // `origin` + branches off `origin/main`, exactly as in the in-repo form.
+    git(['clone', '--quiet', mirrorUrl, claimDir], dirname(claimDir), { env });
+    return {
+        arbiterUrl: mirrorUrl,
+        claimCwd: claimDir,
+        claimArbiter: 'origin',
+        remoteMode: true,
+        cleanup: () => rmSync(claimDir, { recursive: true, force: true }),
+    };
+}
+/**
+ * Create the human worktree at `<root>/<key>/<slug>/` on `work/<slug>`, branched
+ * off the freshly-fetched hub-mirror `main`. The mirror is (re-)fetched here too,
+ * so even in in-repo mode the worktree is cut from the latest arbiter main — the
+ * same-starting-commit guarantee.
+ */
+function createHumanWorktree(params) {
+    const { slug, root, arbiterUrl, workspacesDir, env } = params;
+    // Ensure the hub mirror exists, then refresh ONLY `main` to the latest arbiter
+    // tip (which, post-claim, includes the claim move). We do NOT use the pruning
+    // mirror-fetch here: this mirror also holds the LOCAL-ONLY `work/<slug>`
+    // branches of other live human worktrees, and a pruning fetch would delete
+    // (and corrupt) them. fetchMirrorMain refreshes main without touching them.
+    const hubPath = mirrorPath(workspacesDir, arbiterUrl);
+    let mirrorUrl = arbiterUrl;
+    if (existsSync(hubPath)) {
+        fetchMirrorMain(hubPath, env);
+    }
+    else {
+        mirrorUrl = ensureMirror({ url: arbiterUrl, workspacesDir, env }).url;
+    }
+    const key = encodeRepoKey(mirrorUrl);
+    // `work-on` builds a TASK in a worktree — the task-namespaced work branch.
+    const branch = workBranchRef('task', slug);
+    const dir = join(root, key, slug);
+    // Clear any stale worktree/branch for this slug (idempotent re-run).
+    clearWorktree(hubPath, dir, env);
+    pruneBranch(hubPath, branch, env);
+    mkdirSync(dirname(dir), { recursive: true });
+    git(['worktree', 'add', '--quiet', '-b', branch, dir, 'main'], hubPath, {
+        env,
+    });
+    const startCommit = git(['rev-parse', 'HEAD'], dir, { env }).trim();
+    return { dir, branch, startCommit };
+}
+/**
+ * Copy the named gitignored files into the new worktree (COPY, not symlink). A
+ * fresh worktree has NONE of your untracked files, so a project that needs e.g.
+ * `.env.local` to run won't run without this. Prints a one-line SECURITY NOTICE
+ * naming what was copied and that secrets now live in a second location.
+ *
+ * Source: the current repo in in-repo mode; in remote mode there is no implicit
+ * source, so `--copy` REQUIRES `--copy-from <path>`.
+ */
+function copyGitignoredFiles(params) {
+    const { copy, copyFrom, remoteMode, inRepoSource, destDir, note } = params;
+    if (!copy || copy.trim() === '') {
+        return [];
+    }
+    const patterns = copy
+        .split(',')
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    if (patterns.length === 0) {
+        return [];
+    }
+    const source = resolveCopySource({ remoteMode, copyFrom, inRepoSource });
+    const copied = [];
+    const missing = [];
+    for (const name of patterns) {
+        const from = join(source, name);
+        if (!existsSync(from)) {
+            missing.push(name);
+            continue;
+        }
+        const to = join(destDir, name);
+        mkdirSync(dirname(to), { recursive: true });
+        // Copy (recursively for dirs); explicitly NOT a symlink, so the worktree is
+        // tooling-safe and self-contained.
+        cpSync(from, to, { recursive: true });
+        copied.push(name);
+    }
+    if (missing.length > 0) {
+        note(`!! --copy: not found in ${source} (skipped): ${missing.join(', ')}.`);
+    }
+    if (copied.length > 0) {
+        note(`!! SECURITY NOTICE: copied ${copied.length} gitignored file(s) into the ` +
+            `new worktree: ${copied.join(', ')}. These are real copies (not ` +
+            `symlinks) — secrets now live in a SECOND location (${destDir}). ` +
+            'Treat that worktree like the source for credential hygiene.');
+    }
+    return copied;
+}
+/** Resolve the source dir for `--copy`, enforcing `--copy-from` in remote mode. */
+function resolveCopySource(params) {
+    const { remoteMode, copyFrom, inRepoSource } = params;
+    if (remoteMode) {
+        if (!copyFrom || copyFrom.trim() === '') {
+            throw new WorkOnUsageError('--copy needs an explicit source in remote mode: pass --copy-from <path> ' +
+                '(there is no current repo to copy gitignored files from).');
+        }
+        const src = resolve(copyFrom);
+        if (!existsSync(src) || !statSync(src).isDirectory()) {
+            throw new WorkOnUsageError(`--copy-from path does not exist or is not a directory: ${src}`);
+        }
+        return src;
+    }
+    return inRepoSource;
+}
+/**
+ * Resolve the human worktree root: a configured `humanWorktreesDir` wins; else
+ * prompt for it (a sensible SUGGESTION, no silent default) and SAVE it, so the
+ * human is asked exactly once. NEVER allow a root under `~/.dorfl/` (that
+ * is the agents' execution area — work-on is human-only).
+ */
+async function resolveHumanWorktreesRoot(options, note) {
+    const configured = options.humanWorktreesDir;
+    if (configured && configured.trim() !== '') {
+        return assertHumanRoot(resolve(configured));
+    }
+    if (!options.promptForRoot) {
+        throw new WorkOnUsageError('humanWorktreesDir is not configured and no prompt is available; set ' +
+            '`humanWorktreesDir` in config (a human-only worktree root, NOT under ' +
+            '~/.dorfl/).');
+    }
+    const suggestion = suggestHumanWorktreesDir();
+    const answeredRaw = await options.promptForRoot(suggestion);
+    const answered = (answeredRaw ?? '').trim();
+    if (answered === '') {
+        throw new WorkOnUsageError('no humanWorktreesDir provided — aborting (work-on needs a worktree root).');
+    }
+    const chosen = assertHumanRoot(resolve(answered));
+    if (options.saveRoot) {
+        options.saveRoot(chosen);
+        note(`Saved humanWorktreesDir = ${chosen} to config.`);
+    }
+    return chosen;
+}
+/**
+ * Reject a human worktree root under `~/.dorfl/` (the agents' area, ADR
+ * §3): work-on is human-only and must never share that space.
+ */
+function assertHumanRoot(dir) {
+    const agentArea = join(homedir(), brand.workdirName);
+    const normalized = dir.endsWith('/') ? dir.slice(0, -1) : dir;
+    if (normalized === agentArea || normalized.startsWith(agentArea + '/')) {
+        throw new WorkOnUsageError(`humanWorktreesDir must NOT be under ${agentArea} (that is the agents' ` +
+            'execution area; work-on is human-only). Choose a separate human dir.');
+    }
+    return dir;
+}
+/**
+ * A sensible SUGGESTION for the human worktree root. Deliberately uses a name
+ * (`~/worktrees`) that does NOT share a prefix with the usual code dir
+ * (`~/dev/...`), so shell tab-completion on the code dir never collides with it.
+ * This is only a suggestion — there is no silent default; the human confirms.
+ */
+export function suggestHumanWorktreesDir() {
+    return join(homedir(), 'worktrees');
+}
+/** Remove a worktree registration from the hub (git's own removal, never rm -rf). */
+function clearWorktree(mirrorPath, dir, env) {
+    if (existsSync(dir)) {
+        try {
+            git(['worktree', 'remove', '--force', dir], mirrorPath, { env });
+        }
+        catch {
+            // not a registered worktree — fall through to a plain rm + prune
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    try {
+        git(['worktree', 'prune'], mirrorPath, { env });
+    }
+    catch {
+        // best-effort
+    }
+}
+/** Drop a branch from the hub if it exists (idempotent re-run safety). */
+function pruneBranch(mirrorPath, branch, env) {
+    try {
+        git(['branch', '-D', branch], mirrorPath, { env });
+    }
+    catch {
+        // branch may not exist
+    }
+}
+/**
+ * The canonical arbiter URL a mirror tracks for a given `remote` spec. The
+ * mirror is cloned from `remote`, so the tracked URL is just the trimmed spec
+ * (the same value {@link ensureMirror} would resolve from `url`).
+ */
+function ensureMirrorUrl(remote) {
+    return remote.trim();
+}
+/** Run git, returning the raw result (no throw) — for soft checks. */
+function gitSoft(args, cwd, env) {
+    return runAsync('git', args, cwd, { env });
+}
+/**
+ * Resolve `humanWorktreesDir` + `configPath` for the CLI: read config from
+ * `configPath` and surface its `humanWorktreesDir` (undefined ⇒ first use). The
+ * CLI wires the prompt/save around this; kept here so the wiring is testable.
+ */
+export function loadHumanWorktreesDir(configPath = defaultConfigPath()) {
+    const config = loadConfig(configPath);
+    return { dir: config.humanWorktreesDir, config };
+}
+/** Save a chosen `humanWorktreesDir` back to `configPath`, preserving the rest. */
+export function persistHumanWorktreesDir(dir, configPath = defaultConfigPath()) {
+    const config = loadConfig(configPath);
+    saveConfig({ ...config, humanWorktreesDir: dir }, configPath);
+}
+// Re-export for callers that want the encoding without importing repo-mirror.
+export { encodeRepoKey };
+//# sourceMappingURL=work-on.js.map

package/dist/work-on.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-on.js","sourceRoot":"","sources":["../src/work-on.ts"],"names":[],"mappings":"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"}

package/dist/workspace.d.ts

@@ -0,0 +1,224 @@
+import { type EnsureMirrorResult } from './repo-mirror.js';
+import { type HarnessRecord } from './harness.js';
+import { type SlugNamespace } from './slug-namespace.js';
+/**
+ * The workspace manager (ADR §2): one git worktree per **job** (a claimed work
+ * item being processed), checked out OUTSIDE the bare hub mirror at
+ * `<workspacesDir>/work/<work-id>/`, on branch `work/<slug>`, branched off the
+ * hub's freshly-fetched `main`.
+ *
+ * This is the single isolation primitive (ADR §1: jobs-not-agents) — both the
+ * autonomous `run-once` runner and (later) the human `work-on` build on it. It
+ * consumes the **`repo-mirror`** hub primitive (it does NOT reimplement mirror
+ * management or the repo→key encoding) and leaves a per-job state record (a
+ * `<work-id>.json` SIBLING of the worktree, OUTSIDE the checked-out tree —
+ * {@link jobRecordPath}) + the worktree on disk for `gc`/`status` to read (those
+ * are SEPARATE tasks — this task only provides the state they evaluate).
+ *
+ * `<workspacesDir>` is STATE, not cache (ADR §3): it lives under a single
+ * visible `~/.dorfl/`, never `~/.cache`.
+ */
+/** The on-disk JSON record `gc`/`status` read to evaluate a job. */
+export interface JobRecord {
+    /** The work slug being processed. */
+    slug: string;
+    /** The encoded repo key (the hub mirror key for the arbiter URL). */
+    repoKey: string;
+    /** The work branch checked out in the worktree (`work/<slug>`). */
+    branch: string;
+    /** ISO timestamp the job worktree was created. */
+    startedAt: string;
+    /** Lifecycle state; `gc`/`status` read this alongside the worktree's existence. */
+    state: JobState;
+    /**
+     * Why the job is stuck, when `state` is `needs-attention` (ADR §12). The
+     * runner records the reason it routed the job to needs-attention (a red gate,
+     * a rebase conflict, …) so `status` can surface it without re-deriving it.
+     * Absent for `running`/`done` jobs.
+     */
+    reason?: string;
+    /**
+     * The URL of the review request opened for this job (e.g. a GitHub PR), when
+     * `propose` mode + a real provider (ADR §6) opened one. Recorded so `status`
+     * can surface it. Absent for merge mode, the push-only `none`/degraded path,
+     * and jobs that have not integrated yet.
+     */
+    prUrl?: string;
+    /** The harness block: how this job is launched + its liveness pointer. */
+    harness: HarnessRecord;
+}
+/**
+ * A job's lifecycle state, persisted in its record. The reaper (`gc`) and
+ * `status` read it together with the worktree's existence (ADR §4); this task
+ * only ever sets `running` (and lets the harness/integration update it later).
+ */
+export type JobState = 'running' | 'done' | 'needs-attention';
+/**
+ * Encode a flat, deterministic, unique-per-claim **work-id** from the arbiter
+ * URL + slug: the hierarchical repo key with its `/` separators flattened to
+ * `__`, then `__<slug>` appended (ADR §2). Flat (not hierarchical) so listing /
+ * counting / GC of jobs is a flat `ls`. Reuses the `repo-mirror` repo→key
+ * encoding (dot→dash per segment) — it does NOT duplicate it.
+ *
+ * E.g. `git@github.com:wighawag/dorfl.git` + `feat`
+ *   → `github-com__wighawag__dorfl__feat`.
+ */
+export declare function encodeWorkId(url: string, slug: string): string;
+/**
+ * The on-disk location of a job's worktree: `<workspacesDir>/work/<work-id>/`.
+ * Flat, OUTSIDE the hub (`<workspacesDir>/repos/...`), under `workspacesDir`
+ * (default `~/.dorfl`), never `~/.cache` (ADR §3).
+ */
+export declare function jobWorktreePath(workspacesDir: string, url: string, slug: string): string;
+/** Filename of the per-job record. Derived from the single brand identity
+ * (`.{base}-job.json`) so a rename flips it in lockstep.
+ *
+ * HISTORICAL: this used to be the name of a file written INSIDE the job worktree
+ * (`<work-id>/.dorfl-job.json`). That in-tree location was the mistake —
+ * a runtime control file inside the checked-out worktree got swept onto the work
+ * branch by the runner's broad `git add -A` commits (and once WEDGED a
+ * continue-rebase `git switch`). The record now lives at a SIBLING path OUTSIDE
+ * the worktree ({@link jobRecordPath}); this constant survives only as the
+ * legacy in-tree read-fallback name + as the no-op-build / clean-worktree
+ * classification token in `agent-stop.ts`/`gc.ts` (now inert — the record can no
+ * longer appear in `git status`). */
+export declare const JOB_RECORD_FILENAME: string;
+/**
+ * The on-disk location of a job's state record: a SIBLING of its worktree dir,
+ * `<workspacesDir>/work/<work-id>.json` (NEXT TO `<workspacesDir>/work/<work-id>/`,
+ * NOT inside it).
+ *
+ * This is the structural fix for the in-tree leak: the record is still under the
+ * same `workspacesDir/work/` control area (so `discoverJobs`'s single-directory
+ * walk still finds it), but it is PHYSICALLY OUTSIDE the checked-out git
+ * worktree, so the runner's broad `git add -A` commits can NEVER stage it — in
+ * ANY repo, with no `.gitignore` entry needed. A `<work-id>.json` file name can
+ * never collide with the `<work-id>/` worktree DIR (one carries a `.json`
+ * extension, the other does not).
+ *
+ * Derived purely from the worktree `dir` (sibling = `<dir>.json`) so every
+ * existing caller that holds a worktree dir keeps the same `(dir, …)` signature.
+ */
+export declare function jobRecordPath(dir: string): string;
+export interface CreateJobOptions {
+    /**
+     * The arbiter remote URL to mirror + branch from. Either `url` OR
+     * (`fromRepo` + `arbiter`) must be given; if both, `url` wins.
+     */
+    url?: string;
+    /** A working repo to resolve the arbiter URL from (with `arbiter`). */
+    fromRepo?: string;
+    /** Remote name in `fromRepo` whose URL to mirror (default `origin`). */
+    arbiter?: string;
+    /** The work slug being processed (→ branch `work/<type>-<slug>` + work-id). */
+    slug: string;
+    /**
+     * The item TYPE — `'task'` (build) or `'prd'` (tasking) — namespacing the
+     * work branch via {@link workBranchRef} so a same-slug task and prd never
+     * collide. Defaults to `'task'`.
+     */
+    type?: SlugNamespace;
+    /** The execution working area (config `workspacesDir`, default `~/.dorfl`). */
+    workspacesDir: string;
+    /** The initial harness block to persist in the record (default: null adapter). */
+    harness?: HarnessRecord;
+    env?: NodeJS.ProcessEnv;
+}
+export interface Job {
+    /** Working directory the agent + tests run in (the worktree). */
+    dir: string;
+    /** The work branch checked out there (`work/<slug>`). */
+    branch: string;
+    /** The slug being processed. */
+    slug: string;
+    /**
+     * The git remote name VALID INSIDE the worktree that tracks the arbiter. A
+     * job worktree is cut from the bare hub mirror, whose clone remote is
+     * `origin` (pointing at the arbiter URL). So rebase/integrate inside the
+     * worktree always target `origin`, regardless of what the source working repo
+     * calls its arbiter remote.
+     */
+    arbiterRemote: string;
+    /** Absolute path to the per-job record. */
+    recordPath: string;
+    /** The persisted record. */
+    record: JobRecord;
+    /** The hub-mirror result this job was cut from. */
+    mirror: EnsureMirrorResult;
+    /**
+     * True iff this job CONTINUED a kept arbiter `work/<slug>` branch (a requeue)
+     * rather than cutting fresh off main — the worktree was cut from that branch
+     * and rebased onto the freshly-fetched main at onboard-time (ADR §10).
+     */
+    continued: boolean;
+    /**
+     * True iff a CONTINUE rebase onto fresh main CONFLICTED (aborted, never
+     * auto-resolved). The caller (`run`'s pipeline / `do --remote`) routes the
+     * item to needs-attention via the §10 path; the worktree is left on the
+     * un-rebased kept branch as the never-lose-work signal.
+     */
+    continueRebaseConflict: boolean;
+    /**
+     * Set iff the CONTINUE reconcile push to the arbiter FAILED TERMINALLY (the
+     * stale-lease retry cap was exhausted, or a non-stale-lease rejection such as
+     * a protected ref / an unreachable arbiter) — the helper THROWS, and we catch
+     * it here so the run does NOT crash leaving the task silently in-progress on
+     * the arbiter (the stale-lease-strand bug). The caller routes the item to
+     * needs-attention, the kept work left committed + recoverable on the branch.
+     * Absent on a fresh cut, a clean continue that pushed, and a rebase conflict
+     * (which sets {@link continueRebaseConflict} instead).
+     */
+    continuePushFailure?: string;
+    /**
+     * Remove the job's worktree + work branch from the hub (`git worktree remove`
+     * + prune; never a bare `rm -rf`, ADR §4). NOTE: the SAFE-to-delete predicate
+     * (ADR §4) is owned by the `gc` task — this is only the mechanical teardown
+     * the runner uses after a job is provably saved.
+     */
+    dispose(): void;
+}
+/**
+ * Create (or recreate) a job: ensure the hub mirror via `repo-mirror`, then
+ * `git worktree add` a per-job worktree OUTSIDE the hub at
+ * `<workspacesDir>/work/<work-id>/` on `work/<slug>`, branched off the
+ * freshly-fetched `<hub>/main`. Writes the per-job record at a SIBLING of the
+ * worktree (`<work-id>.json`, OUTSIDE the tree — {@link jobRecordPath}).
+ *
+ * Distinct slugs ⇒ distinct `work/<slug>` branches, so git's one-branch-per-
+ * worktree constraint is naturally avoided (ADR §2). If a stale worktree/branch
+ * for this work-id already exists it is cleared first (idempotent re-create).
+ */
+export declare function createJob(options: CreateJobOptions): Job;
+/**
+ * Write (or overwrite) a job's record to its SIBLING path ({@link jobRecordPath},
+ * `<work-id>.json` next to the worktree), OUTSIDE the checked-out tree. `dir` is
+ * the worktree dir, kept as the parameter so every caller is unchanged.
+ */
+export declare function writeJobRecord(dir: string, record: JobRecord): void;
+/**
+ * Read a job's record given its worktree `dir`, or `undefined` if absent/invalid.
+ *
+ * Reads the NEW sibling location ({@link jobRecordPath}) first, then falls back
+ * to the LEGACY in-tree location (`<dir>/.dorfl-job.json`) so a job
+ * worktree materialised by an OLD binary (record still inside the tree) stays
+ * discoverable/reapable until it is torn down. New jobs only ever write the
+ * sibling path, so the fallback is purely for in-flight migration.
+ */
+export declare function readJobRecord(dir: string): JobRecord | undefined;
+/**
+ * Delete a job's record on teardown — BOTH the new sibling path
+ * ({@link jobRecordPath}) and the legacy in-tree path (an old-binary worktree).
+ * Best-effort + idempotent (a missing file is fine). Called when a worktree is
+ * removed (reaped / disposed / cleared) so the relocated record does not outlive
+ * its worktree as an orphan `<work-id>.json` (when the record lived INSIDE the
+ * worktree it was deleted WITH it by `git worktree remove`; now that it is a
+ * sibling, its teardown must be explicit).
+ */
+export declare function removeJobRecord(dir: string): void;
+/**
+ * Update a job's record in place (e.g. flip `state` to `needs-attention` after a
+ * rebase conflict), merging the patch over the on-disk record. A no-op if no
+ * record exists.
+ */
+export declare function updateJobRecord(dir: string, patch: Partial<JobRecord>): JobRecord | undefined;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAGA,OAAO,EAGN,KAAK,kBAAkB,EACvB,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EAAC,KAAK,aAAa,EAAC,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAgB,KAAK,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAEtE;;;;;;;;;;;;;;;;GAgBG;AAEH,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACzB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,mFAAmF;IACnF,KAAK,EAAE,QAAQ,CAAC;IAChB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,OAAO,EAAE,aAAa,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GACjB,SAAS,GACT,MAAM,GACN,iBAAiB,CAAC;AAErB;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GACV,MAAM,CAER;AAED;;;;;;;;;;;qCAWqC;AACrC,eAAO,MAAM,mBAAmB,QAA0B,CAAC;AAE3D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AASD,MAAM,WAAW,gBAAgB;IAChC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,GAAG;IACnB,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,MAAM,EAAE,SAAS,CAAC;IAClB,mDAAmD;IACnD,MAAM,EAAE,kBAAkB,CAAC;IAC3B;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,sBAAsB,EAAE,OAAO,CAAC;IAChC;;;;;;;;;OASG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAC;CAChB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,GAAG,CAsIxD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAEnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAYhE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CASjD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC9B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,GACvB,SAAS,GAAG,SAAS,CAQvB"}