dorfl 0.0.0 → 0.1.0

package/src/select-order.ts

@@ -0,0 +1,143 @@
+/**
+ * The pure SELECTION-ORDER resolver: turn the per-repo `selectionOrder` config
+ * value (a PRESET keyword OR an explicit pool-name list) into the canonical
+ * ordered list of the FOUR orderable pools, which {@link selectPrioritised}
+ * interleaves AFTER the always-first `apply` pool.
+ *
+ * Two load-bearing rules (ADR `ci-config-policy-and-gate-family`, selection-order
+ * section; task `advance-selection-order-config`):
+ *
+ *  1. **`apply` is PINNED FIRST and is NOT nameable here.** Consuming a human's
+ *     committed answer is highest-value, cheap (no model), and someone is waiting
+ *     — deprioritizing it is never a real want (consume-always-wins). So this
+ *     resolver ranks ONLY the other four; naming `apply` in `selectionOrder` is a
+ *     LOUD usage error (it signals a misunderstanding — `apply` cannot be reordered).
+ *  2. **The value is a PRESET STRING or an explicit ORDER LIST** (the preset is
+ *     sugar over a list; the canonical form is the list). A single recognized
+ *     preset keyword EXPANDS to its list; ANYTHING else is parsed as an explicit
+ *     pool-name list, validating each name. An unknown pool name OR an unknown
+ *     single keyword FAILS LOUDLY naming the offending value.
+ *
+ * Pure: no I/O, no config read. The callers resolve `config.selectionOrder`
+ * through this, then hand the ordered list to {@link selectPrioritised}.
+ */
+
+/**
+ * The four ORDERABLE pools (the ones `selectionOrder` ranks). `apply` is
+ * deliberately ABSENT — it is pinned first and not configurable, so it is not a
+ * member of this union and naming it is a usage error.
+ *
+ *  - `build` — build an eligible task;
+ *  - `task` — task a taskable prd;
+ *  - `surface` — render a `needsAnswers` blocker into an answerable sidecar;
+ *  - `triage` — triage an untriaged observation.
+ */
+export type SelectionPool = 'build' | 'task' | 'surface' | 'triage';
+
+/** The orderable pools, in their canonical "drain" order (the default). */
+export const SELECTION_POOLS: readonly SelectionPool[] = [
+	'build',
+	'task',
+	'surface',
+	'triage',
+];
+
+/**
+ * The recognized PRESET keywords, each sugar over an explicit pool-order list:
+ *
+ *  - `drain` (the DEFAULT) — drain ready work, then create, then ask:
+ *    `[build, task, surface, triage]`. Reproduces today's drain-first
+ *    "drain before create" default (`build` before `task`).
+ *  - `groom` — ask/groom first, build later: `[surface, triage, build, task]`.
+ *
+ * Kept deliberately SMALL (the minimize-head-space stance): a third preset earns
+ * its place only when a real need appears.
+ */
+export const SELECTION_ORDER_PRESETS: Record<string, readonly SelectionPool[]> =
+	{
+		drain: ['build', 'task', 'surface', 'triage'],
+		groom: ['surface', 'triage', 'build', 'task'],
+	};
+
+/** The default `selectionOrder` value when unset (the `drain` preset). */
+export const DEFAULT_SELECTION_ORDER = 'drain';
+
+/**
+ * The config value a user writes for `selectionOrder`: a preset keyword (or a
+ * single explicit pool name) as a STRING, or an explicit ordered LIST of pool
+ * names (the env `'list'` coercion always yields the list form).
+ */
+export type SelectionOrderConfig = string | string[];
+
+const POOL_SET = new Set<string>(SELECTION_POOLS);
+const PRESET_NAMES = Object.keys(SELECTION_ORDER_PRESETS);
+
+/**
+ * Resolve a `selectionOrder` config value into the canonical ordered list of the
+ * four orderable pools. A single recognized preset keyword expands to its list;
+ * anything else is treated as an explicit pool-name list (each name validated).
+ *
+ * FAILS LOUDLY (throws) on:
+ *  - an unknown SINGLE keyword (not a preset AND not a pool name);
+ *  - an unknown pool name anywhere in an explicit list;
+ *  - naming `apply` (it is pinned first, not orderable);
+ *  - an empty order (no pools named);
+ *  - a duplicate pool name in an explicit list.
+ *
+ * The list form is taken VERBATIM (no implicit padding of omitted pools — a list
+ * names exactly the orderable pools the user wants, in order; an omitted pool is
+ * simply ranked nowhere, which only matters if that pool is present, see the gate
+ * orthogonality note in {@link selectPrioritised}).
+ */
+export function resolveSelectionOrder(
+	value: SelectionOrderConfig,
+): SelectionPool[] {
+	// Normalise to a list of trimmed, non-empty tokens. A bare string is one token
+	// (so `'drain'` and `['drain']` resolve identically — the env single-keyword
+	// case); a list is its trimmed entries.
+	const tokens = (typeof value === 'string' ? [value] : value)
+		.map((t) => t.trim())
+		.filter((t) => t !== '');
+
+	// A SINGLE token that is a recognized preset keyword expands to its list. This
+	// is the ONLY place a preset is honoured: a preset keyword mixed into a
+	// multi-element list is NOT a pool name and so fails loudly below.
+	if (tokens.length === 1 && tokens[0] in SELECTION_ORDER_PRESETS) {
+		return [...SELECTION_ORDER_PRESETS[tokens[0]]];
+	}
+
+	if (tokens.length === 0) {
+		throw new Error(
+			`Invalid selectionOrder: empty. Expected a preset ` +
+				`(${PRESET_NAMES.join(' / ')}) or an explicit pool-order list ` +
+				`(${SELECTION_POOLS.join(', ')}).`,
+		);
+	}
+
+	// Otherwise an EXPLICIT pool-name list: validate each name is a known orderable
+	// pool, failing loudly on `apply` (pinned, not orderable) or any unknown name.
+	const seen = new Set<string>();
+	const order: SelectionPool[] = [];
+	for (const token of tokens) {
+		if (token === 'apply') {
+			throw new Error(
+				`Invalid selectionOrder: 'apply' is pinned FIRST and is not ` +
+					`orderable — remove it. selectionOrder ranks only: ` +
+					`${SELECTION_POOLS.join(', ')}.`,
+			);
+		}
+		if (!POOL_SET.has(token)) {
+			throw new Error(
+				`Invalid selectionOrder: unknown pool '${token}'. Expected a preset ` +
+					`(${PRESET_NAMES.join(' / ')}) or pool names from: ` +
+					`${SELECTION_POOLS.join(', ')}.`,
+			);
+		}
+		if (seen.has(token)) {
+			throw new Error(`Invalid selectionOrder: duplicate pool '${token}'.`);
+		}
+		seen.add(token);
+		order.push(token as SelectionPool);
+	}
+	return order;
+}

package/src/select-priority.ts

@@ -0,0 +1,266 @@
+import {selectCandidates, type Candidate, type SelectCaps} from './select.js';
+import type {ScanReport} from './scan.js';
+import {
+	resolveTaskingEligibility,
+	type HumanOnlyGate,
+} from './tasking-eligibility.js';
+import {
+	resolveSelectionOrder,
+	DEFAULT_SELECTION_ORDER,
+	type SelectionPool,
+	type SelectionOrderConfig,
+} from './select-order.js';
+
+/**
+ * The SHARED, PURE selection-and-ordering helper for the multi-item `do`/`advance`
+ * forms (auto-pick / `-n <x>` / `<a> <b> …`) and the CONFIGURABLE selection ORDER
+ * (task `advance-selection-order-config`; ADR `ci-config-policy-and-gate-family`,
+ * selection-order section). `apply` is PINNED FIRST (consume-always-wins); the
+ * other four pools (`build` / `task` / `surface` / `triage`) are ranked by the
+ * per-repo `selectionOrder` field (a PRESET keyword or an explicit pool-name
+ * list), whose `drain` default reproduces today's tasks-first "drain ready work
+ * before creating more".
+ *
+ * It is the ONE place the cross-pool ordering lives, so it is not duplicated when
+ * `run`'s tick later adopts the SAME priority
+ * (ADR §3: "the `run`/`do` auto-task step"). This task (`do-autopick`) OWNS and
+ * builds this helper; it does NOT retro-wire `run` to call it (at `do-autopick`
+ * time `run`'s tick is task-only — concurrent + looped — and adopting this
+ * helper, so `run` also auto-tasks eligible prds, is a noted FOLLOW-UP once both
+ * land). Build it standalone; do not assume `run` already calls it.
+ *
+ * **Up to FIVE pools.** The `scan`/`selectCandidates`/eligibility model is
+ * TASK-ONLY (there is no prd candidate). So this helper composes:
+ *
+ *   - the **`build` pool** (eligible TASKS) — the EXISTING {@link selectCandidates}
+ *     path (round-robin across repos, capped). This is the EXACT task-selection
+ *     primitive `run` uses, so `run` and this helper SHARE it (they share
+ *     `selectCandidates`, the task-pool core).
+ *   - the **`task` pool** (prd-to-task) — a pool the caller builds from the prd reader
+ *     (`ledgerRead.resolveSpecPool`) filtered by `autoslice-gate`'s pure predicate
+ *     ({@link resolveTaskingEligibility}); see {@link taskableSpecs}. The helper
+ *     does NOT reinvent prd eligibility.
+ *
+ * `do` is STRICTLY SEQUENTIAL (parallelism is `run`'s job, ADR §3) — this helper
+ * only ORDERS + COUNTS the items; the caller runs the existing `do` pipeline per
+ * item one at a time. `count` bounds how many items are taken (auto-pick = 1,
+ * `-n <x>` = x). It is NOT a parallelism knob.
+ */
+
+/**
+ * Which namespace a selected item names (mirrors the slug-namespace split). The
+ * `do` selection only ever produces `task`/`prd`; the `advance` selection ALSO
+ * produces `observation` (the lifecycle triage pool, task
+ * `advance-autopick-lifecycle-pools`), so a selected lifecycle item carries which
+ * rung the driver dispatches to. The widening is BACKWARD-COMPATIBLE: `do` never
+ * emits `observation` (its lifecycle pools default to none, see
+ * {@link selectPrioritised}).
+ */
+export type SelectedNamespace = 'task' | 'spec' | 'observation';
+
+/** One item the selection layer picked, in run order. */
+export interface SelectedItem {
+	/** The repo this item lives in (a working checkout for in-place `do`). */
+	repoPath: string;
+	/** The bare slug to act on. */
+	slug: string;
+	/**
+	 * `'task'` ⇒ run the task-build `do` pipeline; `'spec'` ⇒ dispatch to the
+	 * `do spec:<slug>` tasking path (tasking itself is `autoslice-command`, not
+	 * here); `'observation'` ⇒ (advance only) the triage rung via `obs:<slug>`. The
+	 * caller turns this into the right `do`/`advance` arg/dispatch.
+	 */
+	namespace: SelectedNamespace;
+}
+
+/**
+ * A lifecycle-pool selected item (task `advance-autopick-lifecycle-pools`). It is
+ * a {@link SelectedItem} — the same shape — carrying the lifecycle namespace
+ * (`observation` for triage; `task`/`prd` for a `needsAnswers`-blocked item the
+ * tick will surface/apply). A distinct alias names the lifecycle pools at the
+ * call sites WITHOUT a structural difference (the discriminator is `namespace`).
+ */
+export type LifecycleSelectedItem = SelectedItem;
+
+/** A prd candidate for the tasking pool, before the eligibility gate runs. */
+export interface SpecCandidate {
+	repoPath: string;
+	slug: string;
+	humanOnly: HumanOnlyGate;
+	needsAnswers: HumanOnlyGate;
+	taskedAfter: string[];
+}
+
+/** Inputs to {@link taskableSpecs}: the raw prd pool + the gate context. */
+export interface TaskableSpecsInput {
+	/** Every prd enumerated from `work/prds/ready/` (the auto-task candidate source). */
+	candidates: SpecCandidate[];
+	/** Slugs whose prd resides in `work/prds/tasked/` (resolves `taskedAfter`). */
+	taskedSlugs: Set<string>;
+	/** The repo's resolved `autoTask` policy (`autoslice-gate`'s per-repo key). */
+	autoTask: boolean;
+}
+
+/**
+ * Filter a raw prd pool down to the TASKABLE prds, in declaration order, using
+ * `autoslice-gate`'s pure predicate ({@link resolveTaskingEligibility}) — NOT a
+ * reinvented eligibility model. A prd is taskable iff `needsAnswers !== true &&
+ * humanOnly !== true && autoTask` AND every `taskedAfter` prd is already tasked.
+ * Pure: no I/O (the caller reads the pool through `ledgerRead.resolveSpecPool`).
+ */
+export function taskableSpecs(input: TaskableSpecsInput): SpecCandidate[] {
+	return input.candidates.filter(
+		(spec) =>
+			resolveTaskingEligibility({
+				humanOnly: spec.humanOnly,
+				needsAnswers: spec.needsAnswers,
+				taskedAfter: spec.taskedAfter,
+				taskedSlugs: input.taskedSlugs,
+				autoTask: input.autoTask,
+			}).taskable,
+	);
+}
+
+/** Inputs to {@link selectPrioritised}: the pools + ordering + count. */
+export interface SelectPrioritisedInput {
+	/**
+	 * The task pool source — a `scan` report (task-only, the existing model) +
+	 * the concurrency/selection caps. The helper runs the EXISTING
+	 * {@link selectCandidates} over it, so the task ordering is byte-identical to
+	 * what `run` selects (the shared primitive).
+	 */
+	report: ScanReport;
+	/** Caps for the task-pool selection (round-robin/per-repo/total). */
+	caps: SelectCaps;
+	/**
+	 * The ALREADY-FILTERED taskable spec pool (run {@link taskableSpecs} first).
+	 * In declaration order; this helper does not re-gate them.
+	 */
+	specs: SpecCandidate[];
+	/**
+	 * The configurable selection ORDER across the four ORDERABLE pools (`build` /
+	 * `task` / `surface` / `triage`), as a PRESET keyword or an explicit pool-name
+	 * list (task `advance-selection-order-config`; the `selectionOrder` config
+	 * field). Resolved through {@link resolveSelectionOrder} (apply is pinned first
+	 * and NOT nameable here). OMITTED ⇒ the `drain` default (`[build, task,
+	 * surface, triage]`), which reproduces today's tasks-first "drain before
+	 * create" two-pool default. `[task, build, ...]` reproduces the old
+	 * `prdsFirst: true`. An unknown name/keyword FAILS LOUDLY.
+	 */
+	selectionOrder?: SelectionOrderConfig;
+	/**
+	 * How many items to take across ALL pools, in priority order. Auto-pick = 1;
+	 * `do -n <x>` = x. Unset ⇒ take ALL eligible items (the priority order is still
+	 * applied). Sequential — NOT a parallelism knob.
+	 */
+	count?: number;
+	/**
+	 * The OPTIONAL lifecycle pools (task `advance-autopick-lifecycle-pools`),
+	 * constructed CALLER-SIDE (the `advance` callers only) and passed in — exactly
+	 * as {@link prds} is. DEFAULTS to none, so `performDoAuto` (which passes only
+	 * its two pools) is provably UNCHANGED: `do` auto-pick never selects an
+	 * observation or a `needsAnswers` item. ONLY the `advance` callers
+	 * (`performAdvanceAuto` / the mirror-side advance path) supply these.
+	 *
+	 * Ordered per the resolved {@link selectionOrder}: `apply` is ALWAYS prepended
+	 * (pinned first — consume-always-wins), then the four orderable pools (`build` /
+	 * `task` / `surface` / `triage`) in the configured order, truncated to
+	 * {@link count}. A pool NAMED in the order but absent here (gated off — empty)
+	 * is simply a no-op (it contributes no items), so the gates (what is PRESENT)
+	 * and `selectionOrder` (what runs first) compose ORTHOGONALLY.
+	 */
+	lifecycle?: SelectedLifecyclePools;
+	/**
+	 * The HELD-SLUG set to SUBTRACT from the `build` pool (eligible TASKS) — prd
+	 * `ledger-status-per-item-lock-refs` US #15, task
+	 * `claim-acquires-unified-lock-no-body-move`. A task whose per-item lock is
+	 * currently held is dropped from selection, so the eligible pool is "in
+	 * `backlog/` on `main` AND no lock held". Normally the `report` is already
+	 * subtracted at {@link scoreItems} time (the readers gather held locks), so this
+	 * is a SECOND, explicit guard for callers that build the report WITHOUT the
+	 * subtraction; OMITTED ⇒ no extra filtering. Redundant-but-harmless while the
+	 * body still moves to `in-progress/`; in force for task #9.
+	 */
+	heldSlugs?: Set<string>;
+}
+
+/** The (optional) lifecycle pools handed to {@link selectPrioritised}, pre-built. */
+export interface SelectedLifecyclePools {
+	/** `apply` items (answered sidecars; CONSUME, always present when supplied). */
+	apply: LifecycleSelectedItem[];
+	/** `surface` items (blocked, no all-answered sidecar; already gate-filtered). */
+	surface: LifecycleSelectedItem[];
+	/** `triage` items (untriaged observations; already gate-filtered). */
+	triage: LifecycleSelectedItem[];
+}
+
+/**
+ * Build the ordered, counted list of items to do across the (up to) FIVE pools,
+ * applying the configurable {@link selectionOrder} with `apply` PINNED FIRST and
+ * the count bound. The task pool is selected via the EXISTING
+ * {@link selectCandidates} (the shared primitive `run` uses); the prd pool is the
+ * pre-filtered {@link taskableSpecs} output; the lifecycle pools (`apply` /
+ * `surface` / `triage`) are caller-built (none for `do`).
+ *
+ * Ordering: `apply` is always prepended (consume-always-wins; not orderable),
+ * then the four orderable pools (`build` = eligible tasks, `task` = taskable
+ * prds, `surface`, `triage`) interleaved in the resolved {@link selectionOrder}
+ * (default `drain` = `[build, task, surface, triage]`, which reproduces today's
+ * tasks-first two-pool default). A pool named in the order but EMPTY (gated off)
+ * contributes nothing — a no-op, not an error (gates decide what is PRESENT,
+ * `selectionOrder` ranks what is present). Then truncated to `count`.
+ *
+ * Deterministic + pure. The caller runs the existing `do` pipeline per returned
+ * item, SEQUENTIALLY.
+ */
+export function selectPrioritised(
+	input: SelectPrioritisedInput,
+): SelectedItem[] {
+	const held = input.heldSlugs;
+	const buildItems: SelectedItem[] = selectCandidates(input.report, input.caps)
+		.filter((candidate: Candidate) => !held || !held.has(candidate.slug))
+		.map((candidate: Candidate) => ({
+			repoPath: candidate.repoPath,
+			slug: candidate.slug,
+			namespace: 'task' as const,
+		}));
+
+	const taskItems: SelectedItem[] = input.specs.map((spec) => ({
+		repoPath: spec.repoPath,
+		slug: spec.slug,
+		namespace: 'spec' as const,
+	}));
+
+	const lifecycle = input.lifecycle;
+
+	// The per-pool item lists, keyed by the orderable pool name. NOTE the
+	// vocabulary bridge: `build` = the eligible-TASK pool (namespace `task`),
+	// `task` = the taskable-prd pool (namespace `prd`) — the action names, not the
+	// item namespaces (task `advance-selection-order-config`).
+	const byPool: Record<SelectionPool, SelectedItem[]> = {
+		build: buildItems,
+		task: taskItems,
+		surface: lifecycle?.surface ?? [],
+		triage: lifecycle?.triage ?? [],
+	};
+
+	// Resolve the configured order (preset or explicit list; unknown name/keyword
+	// FAILS LOUDLY here). OMITTED ⇒ the `drain` default.
+	const order = resolveSelectionOrder(
+		input.selectionOrder ?? DEFAULT_SELECTION_ORDER,
+	);
+
+	// `apply` is ALWAYS first (pinned, not orderable), then the four orderable
+	// pools in the resolved order. An absent (gated-off) pool's list is empty, so it
+	// drops out cleanly — no special-casing.
+	const applyItems = lifecycle?.apply ?? [];
+	const ordered: SelectedItem[] = [
+		...applyItems,
+		...order.flatMap((pool) => byPool[pool]),
+	];
+
+	if (input.count === undefined) {
+		return ordered;
+	}
+	return ordered.slice(0, Math.max(0, input.count));
+}

package/src/select.ts

@@ -0,0 +1,62 @@
+import type {ScanReport} from './scan.js';
+
+/** One item the runner intends to claim+run, identified by repo + slug. */
+export interface Candidate {
+	repoPath: string;
+	slug: string;
+}
+
+export interface SelectCaps {
+	/** Global cap on items claimed+run in one tick. */
+	maxParallel: number;
+	/** Per-repo cap on concurrent claims. */
+	perRepoMax: number;
+}
+
+/**
+ * Build the ordered list of candidates to attempt from a `scan` report,
+ * respecting the concurrency caps. Only eligible items are considered. Selection
+ * is round-robin across repos for fairness (so a single busy repo cannot starve
+ * the others under `maxParallel`), capping each repo at `perRepoMax` and the
+ * total at `maxParallel`. Deterministic: repos and items are already sorted by
+ * the scan core.
+ *
+ * NOTE: this is optimistic selection only — actual ownership is decided by the
+ * arbiter when the claim CAS runs. A candidate that loses the race is dropped then.
+ */
+export function selectCandidates(
+	report: ScanReport,
+	caps: SelectCaps,
+): Candidate[] {
+	// Per-repo queues of eligible slugs, preserving scan order.
+	const queues = report.repos.map((repo) => ({
+		path: repo.path,
+		slugs: repo.items
+			.filter((item) => item.eligibility.eligible)
+			.map((item) => item.slug),
+		taken: 0,
+	}));
+
+	const picks: Candidate[] = [];
+	let progress = true;
+	while (picks.length < caps.maxParallel && progress) {
+		progress = false;
+		for (const queue of queues) {
+			if (picks.length >= caps.maxParallel) {
+				break;
+			}
+			if (queue.taken >= caps.perRepoMax) {
+				continue;
+			}
+			const next = queue.slugs[queue.taken];
+			if (next === undefined) {
+				continue;
+			}
+			picks.push({repoPath: queue.path, slug: next});
+			queue.taken++;
+			progress = true;
+		}
+	}
+
+	return picks;
+}

package/src/session-path.ts

@@ -0,0 +1,153 @@
+import {homedir} from 'node:os';
+import {join, resolve} from 'node:path';
+
+/**
+ * pi's env override for its agent dir. Real pi reads
+ * `${APP_NAME.toUpperCase()}_CODING_AGENT_DIR` (i.e. `PI_CODING_AGENT_DIR`) in its
+ * `getAgentDir()` (verified vs pinned source `config.ts`); when set, ALL of pi's
+ * default session paths move under it. dorfl's replica MUST honour the same
+ * var, or a user/CI that points pi at a custom agent dir would have dorfl
+ * write sessions to `~/.pi/agent/sessions` while pi reads the custom dir — sessions
+ * then invisible to pi AND pi-remote (the very breakage this task fixes). Also the
+ * clean lever for test isolation (point it at a scratch dir). NOTE: we honour only
+ * the agent-dir var, not pi's separate `PI_CODING_AGENT_SESSION_DIR` — dorfl
+ * already has its own `sessionsDir` override for that role.
+ */
+const PI_AGENT_DIR_ENV = 'PI_CODING_AGENT_DIR';
+
+/** Expand a leading `~`/`~/` to the home dir (pi's `expandTildePath` behaviour). */
+function expandTilde(p: string): string {
+	if (p === '~') {
+		return homedir();
+	}
+	if (p.startsWith('~/') || p.startsWith('~\\')) {
+		return join(homedir(), p.slice(2));
+	}
+	return p;
+}
+
+/**
+ * Generate the **full pi session-file path** the harness passes as `--session
+ * <path>` (task `session-path-pi-default`). This is the single source of the
+ * session path: the caller generates it ONCE (before pi launches, so the
+ * `do --watch` tailer can tail the KNOWN path) and threads it into BOTH the
+ * adapter (`LaunchInput.session`) and the tailer.
+ *
+ * ## Why a full FILE path, not `--session-dir`
+ *
+ * dorfl used to pin `--session-dir <cwd>/.dorfl-pi-session`, which
+ * (1) hid sessions from the pi-remote dashboard (`SessionManager.listAll()` only
+ * scans `~/.pi/agent/sessions/`), (2) made `do --watch` race onto a stale
+ * prior-run log (newest-by-mtime in a shared dir), and (3) polluted the in-place
+ * checkout with an untracked dir. Passing `--session <full-path>` fixes all
+ * three: pi creates+writes the session at exactly that path, it takes precedence
+ * over `--session-dir`, and the watcher tails a path it knew before pi started.
+ *
+ * ## The four load-bearing pi `--session` invariants (verified vs pinned pi
+ * source `core/session-manager.ts` + `main.ts` `resolveSessionPath`)
+ *
+ *  1. **The arg MUST be PATH-SHAPED — absolute and ending `.jsonl`.** pi's
+ *     `resolveSessionPath` takes the file-path branch ONLY when the arg contains
+ *     a slash OR ends `.jsonl`; otherwise it treats the arg as a session-ID to
+ *     look up, fails `not_found`, and pi EXITS 1. So `<sessionsDir>/<id>.jsonl`
+ *     is required (a bare id would kill the run).
+ *  2. **pi creates+writes a NON-EXISTENT `--session` path** (`SessionManager.open`
+ *     on a missing file → `newSession()` pinned to the path). So the FILENAME
+ *     must be UNIQUE PER LAUNCH: a reused name on an existing non-empty file would
+ *     make pi LOAD + APPEND (resume), silently replaying the prior run.
+ *  3. **The header `cwd` falls back to `process.cwd()` for a new file** (no header
+ *     to read), so dashboard repo-grouping is correct ONLY because the adapter
+ *     spawns pi with `cwd: input.dir`. The FOLDER does not imply the repo.
+ *  4. **`listAll` is NON-RECURSIVE (one level):** a session is dashboard-visible
+ *     via the default `listAll()` ONLY as a `.jsonl` DIRECTLY inside a first-level
+ *     subdir of `~/.pi/agent/sessions/` — which the default {@link
+ *     piDefaultSessionDir} (a direct child) gives.
+ *
+ * ## Why the slug helper is replicated, not imported
+ *
+ * dorfl depends ONLY on `commander` (see
+ * `work/notes/observations/task-premise-pi-coding-agent-not-a-dep.md`). pi's exported
+ * `getDefaultSessionDir(cwd)` lives in `@earendil-works/pi-coding-agent`, whose
+ * dependency tree is heavy (`pi-agent-core`, `pi-ai`, `zod`, `ws`). Pulling that
+ * in for one tiny slug function is not worth it, so the encoding is REPLICATED
+ * here (the same choice the do-watch task made for its session-log type). The
+ * encoding is verified verbatim against pinned pi source `getDefaultSessionDirPath`:
+ *
+ *   join(agentDir, 'sessions', `--${resolve(cwd).replace(/^[/\\]/,'').replace(/[/\\:]/g,'-')}--`)
+ *
+ * where `agentDir` is `~/.pi/agent`. If a runtime dep on pi-coding-agent is ever
+ * wanted, swapping this for the import is a one-line change.
+ */
+
+/**
+ * pi's agent dir — the parent of `sessions/`. Honours `PI_CODING_AGENT_DIR`
+ * (matching real pi's `getAgentDir()`), else `~/.pi/agent`. Read at call time (not
+ * cached) so a test setting `process.env.PI_CODING_AGENT_DIR` is respected.
+ */
+function piAgentDir(): string {
+	const override = process.env[PI_AGENT_DIR_ENV];
+	if (override !== undefined && override !== '') {
+		return expandTilde(override);
+	}
+	return join(homedir(), '.pi', 'agent');
+}
+
+/**
+ * pi's DEFAULT per-cwd sessions folder for `cwd` — a direct child of
+ * `~/.pi/agent/sessions/` (invariant #4), so the dashboard's non-recursive
+ * `listAll()` scans it and groups by the session header `cwd`. Replicates pi's
+ * `getDefaultSessionDirPath` encoding verbatim (verified vs pinned source). PURE
+ * (does not create the folder — the parent is ensured at generation time / by
+ * pi's own `SessionManager.open`).
+ */
+export function piDefaultSessionDir(cwd: string): string {
+	const resolvedCwd = resolve(cwd);
+	const safe = `--${resolvedCwd.replace(/^[/\\]/, '').replace(/[/\\:]/g, '-')}--`;
+	return join(piAgentDir(), 'sessions', safe);
+}
+
+/**
+ * Build a filename STEM that is UNIQUE PER LAUNCH (invariant #2). The `id`
+ * (slug for in-place, work-id for job-worktree) is the human-readable anchor; a
+ * timestamp + a short random suffix make it collision-proof even for two
+ * launches in the same millisecond / same checkout reusing the same slug.
+ */
+function uniqueStem(id: string): string {
+	const ts = Date.now().toString(36);
+	const rand = Math.random().toString(36).slice(2, 8);
+	return `${id}-${ts}-${rand}`;
+}
+
+/** Inputs to {@link generateSessionPath}. */
+export interface GenerateSessionPathInput {
+	/**
+	 * The HOST-ONLY sessions root (resolved `config.sessionsDir`). `undefined`
+	 * (unset) ⇒ pi's default per-cwd folder for {@link cwd} (the DYNAMIC default,
+	 * kept in this ONE place — never smeared across config defaulting).
+	 */
+	sessionsDir?: string;
+	/** The job cwd pi is spawned in — used for the unset-default folder. */
+	cwd: string;
+	/**
+	 * A human-readable id for the filename stem (the slug in-place, the work-id
+	 * for a job worktree). Made unique per launch internally.
+	 */
+	id: string;
+}
+
+/**
+ * Generate the absolute, `.jsonl`-ending session FILE path to pass as
+ * `--session <path>` (invariant #1). `<root>/<id>-<unique>.jsonl`, where `<root>`
+ * is the resolved `sessionsDir` or — when unset — pi's default per-cwd folder
+ * (the DYNAMIC default). The path is ABSOLUTE (resolved against the process cwd
+ * if a relative `sessionsDir` was given) and the stem is unique per launch, so a
+ * second launch in the same checkout never appends to / replays the first's
+ * session.
+ */
+export function generateSessionPath(input: GenerateSessionPathInput): string {
+	const root =
+		input.sessionsDir !== undefined && input.sessionsDir !== ''
+			? resolve(input.sessionsDir)
+			: piDefaultSessionDir(input.cwd);
+	return join(root, `${uniqueStem(input.id)}.jsonl`);
+}