@open-agent-toolkit/cli 0.1.39 → 0.1.41

package/dist/commands/pjm/doctor.js

@@ -1,5 +1,6 @@
 import { access, readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { BACKLOG_ITEM_STATUSES, extractBacklogStatus, isTerminalBacklogStatus, isValidBacklogStatus, } from '../backlog/shared/item-status.js';
 import { getFrontmatterBlock } from '../shared/frontmatter.js';
 import { CANONICAL_REPO_REFERENCE_PATHS } from './init.js';
 const ALLOWED_TOP_LEVEL_DIRECTORIES = new Set([
@@ -108,6 +109,45 @@ function containsTemplateFrontmatter(content) {
         (/\boat_template\s*:/i.test(frontmatter) ||
             /\boat_template_name\s*:/i.test(frontmatter)));
 }
+const BACKLOG_ITEMS_DIRECTORY = 'pjm/backlog/items';
+const BACKLOG_ARCHIVED_DIRECTORY = 'pjm/backlog/archived';
+const BACKLOG_COMPLETED_FILE = 'pjm/backlog/completed.md';
+// Best-effort backlog id scan: `BL-YYMMDD-slug` (legacy lowercase `bl-`
+// matched case-insensitively). The six-digit requirement keeps the literal
+// `BL-YYMMDD-slug` format placeholder in `completed.md` from matching.
+const BACKLOG_ID_PATTERN = /\bbl-\d{6}-[a-z0-9][a-z0-9-]*/gi;
+/**
+ * Single frontmatter pass over both backlog directories. Every drift check
+ * derives from this scan so the filesystem is walked once. `index.md` is the
+ * managed index, not an item, so it is excluded.
+ */
+async function collectBacklogItems(repoRoot) {
+    const records = [];
+    const directories = [
+        { directory: 'items', relativeDir: BACKLOG_ITEMS_DIRECTORY },
+        { directory: 'archived', relativeDir: BACKLOG_ARCHIVED_DIRECTORY },
+    ];
+    for (const { directory, relativeDir } of directories) {
+        const fileNames = await listMarkdownFiles(join(repoRoot, relativeDir));
+        for (const fileName of fileNames) {
+            if (fileName === 'index.md') {
+                continue;
+            }
+            const content = await readIfExists(join(repoRoot, relativeDir, fileName));
+            records.push({
+                directory,
+                relativePath: `${relativeDir}/${fileName}`,
+                id: fileName.replace(/\.md$/, ''),
+                status: content ? extractBacklogStatus(content) : null,
+            });
+        }
+    }
+    return records;
+}
+/** Best-effort scan of completed-log content for backlog item ids. */
+function extractCompletedIds(content) {
+    return [...content.matchAll(BACKLOG_ID_PATTERN)].map((match) => match[0]);
+}
 function checkStatus(missing) {
     return missing.length === 0 ? 'pass' : 'fail';
 }
@@ -246,5 +286,126 @@ export async function runPjmDoctorChecks(repoRoot, options = {}) {
             ? undefined
             : 'Move active operational docs to pjm/ and leave reference/ for durable append-mostly artifacts.',
     });
+    const backlogItems = await collectBacklogItems(repoRoot);
+    const terminalInItems = backlogItems
+        .filter((item) => item.directory === 'items' &&
+        item.status !== null &&
+        isTerminalBacklogStatus(item.status))
+        .map((item) => item.relativePath);
+    checks.push({
+        name: 'pjm:backlog_terminal_in_items',
+        description: 'Terminal-status backlog items awaiting archive',
+        status: checkStatus(terminalInItems),
+        message: terminalInItems.length === 0
+            ? 'No terminal-status backlog items remain under items/.'
+            : `Terminal-status backlog items still under items/: ${terminalInItems.join(', ')}`,
+        fix: terminalInItems.length === 0
+            ? undefined
+            : 'Run `oat backlog archive <id>` to move each closed/wont_do item into archived/.',
+    });
+    // A missing/empty `status:` is as much a drift as an out-of-enum value: the
+    // `oat backlog archive` command rejects both, so `pjm doctor` must surface
+    // both rather than leaving status-less items silently invisible.
+    const missingStatusItems = backlogItems
+        .filter((item) => item.status === null || item.status.trim() === '')
+        .map((item) => item.relativePath);
+    const outOfEnumStatusItems = backlogItems
+        .filter((item) => item.status !== null &&
+        item.status.trim() !== '' &&
+        !isValidBacklogStatus(item.status))
+        .map((item) => item.relativePath);
+    const invalidStatus = [...outOfEnumStatusItems, ...missingStatusItems];
+    const invalidStatusDetails = [];
+    if (outOfEnumStatusItems.length > 0) {
+        invalidStatusDetails.push(`out-of-enum status: ${outOfEnumStatusItems.join(', ')}`);
+    }
+    if (missingStatusItems.length > 0) {
+        invalidStatusDetails.push(`missing status: ${missingStatusItems.join(', ')}`);
+    }
+    checks.push({
+        name: 'pjm:backlog_invalid_status',
+        description: 'Backlog items with a missing or out-of-enum status',
+        status: checkStatus(invalidStatus),
+        message: invalidStatus.length === 0
+            ? 'All backlog item statuses are within the valid enum.'
+            : `Backlog items with an invalid status (${invalidStatusDetails.join('; ')}). Valid statuses: ${BACKLOG_ITEM_STATUSES.join(', ')}.`,
+        fix: invalidStatus.length === 0
+            ? undefined
+            : `Set a valid status (${BACKLOG_ITEM_STATUSES.join(', ')}) on each listed item.`,
+    });
+    const archivedOpen = backlogItems
+        .filter((item) => item.directory === 'archived' &&
+        item.status !== null &&
+        isValidBacklogStatus(item.status) &&
+        !isTerminalBacklogStatus(item.status))
+        .map((item) => item.relativePath);
+    checks.push({
+        name: 'pjm:backlog_archived_open',
+        description: 'Archived backlog items with a non-terminal status',
+        status: warnStatus(archivedOpen),
+        message: archivedOpen.length === 0
+            ? 'No archived backlog items carry an open status.'
+            : `Archived backlog items still marked open/in_progress: ${archivedOpen.join(', ')}`,
+        fix: archivedOpen.length === 0
+            ? undefined
+            : 'Set a terminal status (closed/wont_do) on each archived item, or move it back under items/.',
+    });
+    // A single id must never live in both `items/` and `archived/`: the live copy
+    // shadows the archived record and `oat backlog archive` refuses to reconcile
+    // it automatically (auto-archiving would clobber the archived file). Derive
+    // from the same single scan so the filesystem is not re-walked.
+    const backlogPathsByIdAndDir = new Map();
+    for (const item of backlogItems) {
+        const key = item.id.toLowerCase();
+        const entry = backlogPathsByIdAndDir.get(key) ?? {};
+        entry[item.directory] = item.relativePath;
+        backlogPathsByIdAndDir.set(key, entry);
+    }
+    const duplicateIdPairs = [];
+    for (const entry of backlogPathsByIdAndDir.values()) {
+        if (entry.items && entry.archived) {
+            duplicateIdPairs.push(`${entry.items} + ${entry.archived}`);
+        }
+    }
+    checks.push({
+        name: 'pjm:backlog_duplicate_id',
+        description: 'Backlog ids present in both items/ and archived/',
+        status: checkStatus(duplicateIdPairs),
+        message: duplicateIdPairs.length === 0
+            ? 'No backlog id is present in both items/ and archived/.'
+            : `Backlog ids present in both items/ and archived/: ${duplicateIdPairs.join('; ')}`,
+        fix: duplicateIdPairs.length === 0
+            ? undefined
+            : 'Reconcile each duplicate manually: decide whether the active (items/) or archived copy is authoritative, remove the other, then re-run `oat backlog archive <id>` if the item still needs archiving.',
+    });
+    const itemPathsById = new Map();
+    for (const item of backlogItems) {
+        if (item.directory === 'items') {
+            itemPathsById.set(item.id.toLowerCase(), item.relativePath);
+        }
+    }
+    const completedContent = await readIfExists(join(repoRoot, BACKLOG_COMPLETED_FILE));
+    const completedUnarchived = [];
+    const seenUnarchived = new Set();
+    if (completedContent) {
+        for (const completedId of extractCompletedIds(completedContent)) {
+            const relativePath = itemPathsById.get(completedId.toLowerCase());
+            if (relativePath && !seenUnarchived.has(relativePath)) {
+                seenUnarchived.add(relativePath);
+                completedUnarchived.push(relativePath);
+            }
+        }
+    }
+    checks.push({
+        name: 'pjm:backlog_completed_unarchived',
+        description: 'Completed-log entries whose item file is still under items/',
+        status: warnStatus(completedUnarchived),
+        message: completedUnarchived.length === 0
+            ? 'No completed backlog entries reference an item still under items/.'
+            : `Completed log references items still under items/: ${completedUnarchived.join(', ')}`,
+        fix: completedUnarchived.length === 0
+            ? undefined
+            : 'Run `oat backlog archive <id>` to archive each completed item still under items/.',
+    });
     return checks;
 }

package/dist/commands/pjm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAiBnE,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AA6FD,wBAAgB,gBAAgB,CAC9B,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC9C,OAAO,CAsJT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAuB,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAA0B,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAiBnE,UAAU,sBAAsB;IAC9B,mBAAmB,EAAE,OAAO,mBAAmB,CAAC;IAChD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IAC9C,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;CACvD;AA6FD,wBAAgB,gBAAgB,CAC9B,SAAS,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC9C,OAAO,CAuJT"}

package/dist/commands/pjm/index.js

@@ -7,7 +7,7 @@ import { resolveProjectRoot } from '../../fs/paths.js';
 import { formatDoctorResults } from '../../ui/output.js';
 import { Command } from 'commander';
 import { runPjmDoctorChecks } from './doctor.js';
-import { initializeRepoReference } from './init.js';
+import { initializeRepoReference, INSTRUCTIONS_SYNC_HINT } from './init.js';
 import { migratePjmRepo, readPjmMigrationPrompt } from './migrate.js';
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
@@ -111,6 +111,7 @@ export function createPjmCommand(overrides = {}) {
                 if (result.skipped.length > 0) {
                     context.logger.info(`Skipped existing: ${result.skipped.join(', ')}`);
                 }
+                context.logger.info(INSTRUCTIONS_SYNC_HINT);
             }
             process.exitCode = 0;
         }

package/dist/commands/pjm/init.d.ts

@@ -8,6 +8,7 @@ export interface RepoReferenceInitResult {
     created: string[];
     skipped: string[];
 }
-export declare const CANONICAL_REPO_REFERENCE_PATHS: readonly [...("AGENTS.md" | "pjm/AGENTS.md" | "pjm/current-state.md" | "pjm/roadmap.md" | "reference/AGENTS.md")[], "pjm/backlog/index.md", "pjm/backlog/completed.md", "pjm/backlog/items/.gitkeep", "pjm/backlog/archived/.gitkeep", "reference/decisions/index.md"];
+export declare const INSTRUCTIONS_SYNC_HINT: string;
+export declare const CANONICAL_REPO_REFERENCE_PATHS: readonly [...("AGENTS.md" | "pjm/AGENTS.md" | "pjm/current-state.md" | "pjm/roadmap.md" | "reference/AGENTS.md" | "README.md" | "pjm/handoffs/README.md")[], "pjm/backlog/index.md", "pjm/backlog/completed.md", "pjm/backlog/items/.gitkeep", "pjm/backlog/archived/.gitkeep", "reference/decisions/index.md"];
 export declare function initializeRepoReference(options: InitializeRepoReferenceOptions): Promise<RepoReferenceInitResult>;
 //# sourceMappingURL=init.d.ts.map

package/dist/commands/pjm/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAwBD,eAAO,MAAM,8BAA8B,wQAIjC,CAAC;AAyEX,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAgElC"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/commands/pjm/init.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAoBD,eAAO,MAAM,sBAAsB,QAEiD,CAAC;AAWrF,eAAO,MAAM,8BAA8B,iTAIjC,CAAC;AAyEX,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,uBAAuB,CAAC,CAgElC"}

package/dist/commands/pjm/init.js

@@ -9,7 +9,14 @@ const TEMPLATE_TARGETS = [
     { template: 'current-state.md', target: 'pjm/current-state.md' },
     { template: 'roadmap.md', target: 'pjm/roadmap.md' },
     { template: 'reference-agents.md', target: 'reference/AGENTS.md' },
+    { template: 'repo-readme.md', target: 'README.md' },
+    { template: 'pjm-handoffs-readme.md', target: 'pjm/handoffs/README.md' },
 ];
+// Next-step hint printed after init/backfill. `oat pjm init` never writes
+// CLAUDE.md shims itself — strategy ownership stays with `oat instructions
+// sync`, so we point the operator at it (with the `--dry-run` preview).
+export const INSTRUCTIONS_SYNC_HINT = 'Next step: run `oat instructions sync` to create CLAUDE.md shims for the ' +
+    'repo-reference AGENTS.md files (preview with `oat instructions sync --dry-run`).';
 const BACKLOG_PATHS = [
     'pjm/backlog/index.md',
     'pjm/backlog/completed.md',

package/dist/commands/project/dispatch-ceiling/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch-ceiling/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAEL,KAAK,uBAAuB,EAG7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AASzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4BpC,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAggBD,wBAAgB,mCAAmC,CACjD,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAiDT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/project/dispatch-ceiling/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAEL,KAAK,uBAAuB,EAG7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AASzB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6BpC,UAAU,2BAA2B;IACnC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD,sBAAsB,EAAE,CACtB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,GAAG,EAAE,MAAM,CAAC,UAAU,KACnB,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,oBAAoB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC7E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B;AAknBD,wBAAgB,mCAAmC,CACjD,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAqDT"}

package/dist/commands/project/dispatch-ceiling/index.js

@@ -173,12 +173,67 @@ function readResolvedConfigCeiling(provider, resolvedConfig) {
 function normalizeRole(value) {
     return value === 'reviewer' ? 'reviewer' : 'implementer';
 }
+function providerValueOrder(provider) {
+    if (provider === 'codex') {
+        return CODEX_VALUES;
+    }
+    if (provider === 'claude') {
+        return CLAUDE_VALUES;
+    }
+    return null;
+}
+function normalizePreferredValue(provider, value) {
+    if (!value) {
+        return null;
+    }
+    const normalized = value.trim();
+    if (!normalized) {
+        return null;
+    }
+    const order = providerValueOrder(provider);
+    if (!order) {
+        return null;
+    }
+    if (!isValidProviderValue(provider, normalized)) {
+        const validValues = order.join(', ');
+        throw new Error(`Invalid preferred dispatch value "${normalized}" for ${provider}. Valid values: ${validValues}.`);
+    }
+    return normalized;
+}
+function selectDispatchValue(provider, role, ceilingValue, preferredValue) {
+    if (role === 'reviewer' || preferredValue === null) {
+        return {
+            role,
+            preferredValue,
+            selectedValue: ceilingValue,
+            capped: false,
+        };
+    }
+    const order = providerValueOrder(provider);
+    const preferredIndex = order?.indexOf(preferredValue) ?? -1;
+    const ceilingIndex = order?.indexOf(ceilingValue) ?? -1;
+    if (!order || preferredIndex < 0 || ceilingIndex < 0) {
+        return {
+            role,
+            preferredValue,
+            selectedValue: ceilingValue,
+            capped: false,
+        };
+    }
+    const selectedIndex = Math.min(preferredIndex, ceilingIndex);
+    return {
+        role,
+        preferredValue,
+        selectedValue: order[selectedIndex],
+        capped: preferredIndex > ceilingIndex,
+    };
+}
 /**
  * Join a resolved ceiling value with the active provider's adapter to compute
  * the enforcement mode, mechanism, dispatch args, and verify-on-upgrade flag.
  * Mode is computed here at call time — it is never read from persisted state.
  */
-function buildProviderResolution(provider, value, role, orchestratorTier) {
+function buildProviderResolution(provider, value, role, orchestratorTier, preferredValue) {
     const adapter = getCeilingAdapter(provider);
     if (value === null) {
         return {
@@ -187,9 +242,17 @@ function buildProviderResolution(provider, value, role, orchestratorTier) {
             mechanism: adapter.mechanism,
             dispatchArgs: null,
             verifyOnDispatch: false,
+            selection: {
+                role,
+                preferredValue,
+                selectedValue: null,
+                capped: false,
+            },
         };
     }
-    const dispatchArgs = adapter.compileToDispatchArgs(value, role, {
+    const selection = selectDispatchValue(provider, role, value, preferredValue);
+    const dispatchValue = selection.selectedValue ?? value;
+    const dispatchArgs = adapter.compileToDispatchArgs(dispatchValue, role, {
         orchestratorTier,
     });
     let mode;
@@ -207,7 +270,10 @@ function buildProviderResolution(provider, value, role, orchestratorTier) {
         mode,
         mechanism: adapter.mechanism,
         dispatchArgs,
-        verifyOnDispatch: adapter.verifyOnDispatch(value, { orchestratorTier }),
+        verifyOnDispatch: adapter.verifyOnDispatch(dispatchValue, {
+            orchestratorTier,
+        }),
+        selection,
     };
 }
 function readCodexDefaultFromToml(content) {
@@ -257,8 +323,9 @@ async function resolveDispatchCeiling(context, dependencies, options) {
     const providerDefaultEffort = provider === 'codex'
         ? await resolveCodexProviderDefaultEffort(repoRoot, context, dependencies)
         : 'not-applicable';
+    const preferredValue = normalizePreferredValue(provider, options.preferred);
     const resolvedValue = await resolveCeilingValue(provider, resolvedConfig, projectPath, dependencies);
-    const providerResolution = buildProviderResolution(provider, resolvedValue?.value ?? null, role, orchestratorTier);
+    const providerResolution = buildProviderResolution(provider, resolvedValue?.value ?? null, role, orchestratorTier, preferredValue);
     const providers = {
         [provider]: providerResolution,
     };
@@ -332,9 +399,17 @@ function writeHumanResolution(context, resolution) {
     if (resolution.provider === 'codex') {
         context.logger.info(`Codex provider default effort: ${resolution.providerDefaultEffort}`);
         context.logger.info(`Note: OAT will use pinned subagent variants up to ${resolution.value ?? 'the resolved ceiling'}. Base/unpinned roles resolve through the provider default.`);
+        if (providerResolution?.selection.selectedValue &&
+            providerResolution.selection.preferredValue) {
+            context.logger.info(`Selected Codex effort: ${providerResolution.selection.selectedValue}`);
+        }
     }
     else {
         context.logger.info('Effort axis: not-applicable');
+        if (providerResolution?.selection.selectedValue &&
+            providerResolution.selection.preferredValue) {
+            context.logger.info(`Selected dispatch value: ${providerResolution.selection.selectedValue}`);
+        }
     }
 }
 async function runDispatchCeilingResolve(context, dependencies, options) {
@@ -370,6 +445,7 @@ export function createProjectDispatchCeilingCommand(overrides = {}) {
         .requiredOption('--provider <provider>', 'Provider name: codex or claude are enforced; any other provider resolves as advisory (unsupported)')
         .option('--role <role>', 'Dispatch role for variant compilation: implementer (default) or reviewer')
         .option('--orchestrator-tier <tier>', 'Orchestrator tier, used to flag verify-on-upgrade for above-orchestrator requests')
+        .option('--preferred <value>', 'Preferred implementer/fix dispatch value before capping by the resolved ceiling')
         .option('--project-path <path>', 'Read project-state ceiling from an explicit project path')
         .option('--preflight', 'Treat unresolved non-interactive resolution as an implementation block')
         .option('--non-interactive', 'Force non-interactive block behavior when the ceiling is unresolved')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.39"
+    "@open-agent-toolkit/control-plane": "0.1.41"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",