@pitcher/cli-scripts 3.2.0 → 3.3.0

package/dist/src/commands/dsrLanding.js

@@ -79,7 +79,7 @@ export async function runDsrLandingCreate(opts, deps = {}) {
             catch (e) {
                 const err = toCliError(e);
                 return fail(createCliError(err.code, `template created (id ${id}), but set-default failed: ${err.message}. ` +
-                    `Retry with: p dsr-landing set-default --instance-id ${opts.instanceId} --id ${id}`));
+                    `Retry with: p dsr-landing set-default --instance-id ${opts.instanceId} --id ${id}`, err.backendStatus));
             }
         }
         return ok(created);

package/dist/src/commands/roleplay.d.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import type { AxiosInstance } from 'axios';
 import { type CommonOpts } from '../core/http.js';
 import { type Envelope } from '../core/envelope.js';
+import { type AssignmentProgressLike, type RepStatus, type RoleplayAssignmentLike, type RoleplaySessionLike } from '../core/roleplay-stats.js';
 /**
  * AI Roleplay reads (PIT-9200, Phase 1: read-only). Two sources:
  * - clickhouse-api `/analytics/roleplay/{kpis,sessions}` (the `roleplay_statements` replica,
@@ -17,6 +18,7 @@ export interface RoleplayDeps {
 export declare const ROLEPLAY_DIFFICULTIES: readonly ["easy", "medium", "hard"];
 export declare const ROLEPLAY_SESSION_SORT: readonly ["session_at", "rep_name", "score", "duration_ms"];
 export declare const ROLEPLAY_GROUP_BY: readonly ["rep", "scenario"];
+export declare const REP_STATUSES: readonly RepStatus[];
 /** rep-summary reads at most this many pages of this size (5000 sessions), newest first. */
 export declare const REP_SUMMARY_PAGE_SIZE = 1000;
 export declare const REP_SUMMARY_MAX_PAGES = 5;
@@ -25,6 +27,11 @@ export declare const REP_SUMMARY_MAX_GROUPS = 50;
 export declare const COACH_DATA_SESSION_CAP = 1000;
 export declare const TEAM_MAX_ASSIGNMENTS = 50;
 export declare const TEAM_MAX_REPS_PER_ASSIGNMENT = 100;
+/**
+ * Pass progress (PIT-9971) is read in pages of 2000 (assignment, rep) pairs. Above this many pages the
+ * tools use no progress at all (the manager app allows 100,000 pages; one tool call stays bounded).
+ */
+export declare const PROGRESS_MAX_PAGES = 10;
 export interface RoleplayFilterOpts extends CommonOpts {
     instanceId?: string;
     startDate?: string;
@@ -33,6 +40,7 @@ export interface RoleplayFilterOpts extends CommonOpts {
     scenario?: string;
     difficulty?: string;
 }
+export declare const finiteOrNull: (v: unknown) => number | null;
 /** Totals for the window: sessions, scored/unscored, mean score over SCORED sessions only, active reps. */
 export declare function runRoleplayKpis(opts: RoleplayFilterOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
 declare const SESSION_FIELDS: readonly ["entry_id", "session_at", "rep_name", "who", "scenario_name", "persona_name", "difficulty", "score", "evaluated", "rating", "duration_ms"];
@@ -55,15 +63,102 @@ export interface RoleplayRepSummaryOpts extends RoleplayFilterOpts {
  * window holds more than that; then the figures cover the newest 5000 only.
  */
 export declare function runRoleplayRepSummary(opts: RoleplayRepSummaryOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+export interface CoachAssignment extends RoleplayAssignmentLike {
+    id: string;
+    scenarioName?: string;
+    active?: boolean;
+    contentType?: string;
+    resolvedUserNames?: Record<string, string>;
+}
+/** A bundle session row: coach/data spreads the appsDB data and adds the entry `id` (transcript stripped). */
+export type CoachSession = RoleplaySessionLike & {
+    id: string;
+    sessionType?: string;
+    evaluationStatus?: string;
+};
+type ProgressEntry = {
+    assignmentId?: unknown;
+    repUserId?: unknown;
+} & Partial<Record<keyof AssignmentProgressLike, unknown>>;
+interface ProgressPage {
+    page: number;
+    pageSize: number;
+    totalPairs: number;
+    hasMore: boolean;
+}
+/** A `cch-manager-comment` row as coach/data returns it: the appsDB data plus the entry `id` (soft-deleted rows excluded). */
+export type CoachComment = Record<string, unknown> & {
+    id: string;
+    managerId?: string | number;
+    managerName?: string;
+    repUserId?: string | number;
+    assignmentId?: string;
+    sessionEntryId?: string | null;
+    comment?: string;
+};
+export interface CoachBundle {
+    scope?: 'instance' | 'coach';
+    assignments?: CoachAssignment[];
+    sessions?: CoachSession[];
+    comments?: CoachComment[];
+    assignmentProgress?: ProgressEntry[];
+    assignmentProgressPage?: ProgressPage;
+}
 export interface RoleplayTeamOpts extends CommonOpts {
     instanceId?: string;
     assignmentId?: string;
     status?: string;
 }
+export type CoachScope = 'instance' | 'coach';
+/** The caller's OWN coaching scope (coach/data without `scope`): what a coach may comment on (PIT-10113). */
+export declare function getOwnCoachBundle(client: AxiosInstance, instanceId: string): Promise<CoachBundle>;
+/** The manager app's progress map key (`useManagerData.ts`). */
+export declare const progressKey: (assignmentId: string, repUserId: string) => string;
+export interface Coverage {
+    sessionsCapped: boolean;
+    progress: 'full' | 'none';
+    /** (assignment, rep) pairs of the roleplay model with no progress entry when progress is full, else 0. */
+    pairsWithoutProgress: number;
+}
+export interface TeamModel {
+    /** The scope the server applied (an older next-core that ignores scope=instance answers 'coach'). */
+    scope: CoachScope;
+    /** The scope this load asked for first: 'coach' when the caller passed scopePref 'coach'. */
+    requested: CoachScope;
+    coverage: Coverage;
+    warnings: string[];
+    /** contentType !== 'practice', D18 order. */
+    assignments: CoachAssignment[];
+    /** sessionType !== 'manager-video-practice'. */
+    sessions: CoachSession[];
+    progress: ReadonlyMap<string, AssignmentProgressLike> | null;
+}
+/** D18 rep order: the reps who need the manager first. */
+export declare const STATUS_RANK: Record<RepStatus, number>;
+/** D18 assignment order: active first, then due date ascending (none last), then scenario name, then id. */
+export declare function compareAssignments(a: CoachAssignment, b: CoachAssignment): number;
+/** D18 rep order: status rank, then name (no name last), then user id. */
+export declare function compareReps(a: {
+    status: RepStatus;
+    name: string | null;
+    user_id: string;
+}, b: {
+    status: RepStatus;
+    name: string | null;
+    user_id: string;
+}): number;
+/**
+ * The one team derivation shared by `roleplay team` and the roleplay manager view (PIT-10068): the
+ * coach bundle, its pass progress, the roleplay filters and the D18 order, so the text tool and the
+ * view always cut the same 50 assignments.
+ */
+export declare function loadTeamModel(client: AxiosInstance, instanceId: string, scopePref?: CoachScope): Promise<TeamModel>;
 /**
  * Assignment completion per rep, ported from the manager app: an admin gets every roleplay
  * assignment on the instance (`scope=instance`), anyone else the assignments they coach.
- * Statuses follow `deriveStatus`; raw sessions, evaluations and comments never leave.
+ * Statuses, session counts and best scores follow `deriveStatus` / `repStats` with the server's
+ * pass progress when it loads (PIT-9971); assignments and reps in D18 order (`loadTeamModel`).
+ * Raw sessions, evaluations and comments never leave.
  */
 export declare function runRoleplayTeam(opts: RoleplayTeamOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
 export interface RoleplaySessionGetOpts extends CommonOpts {
@@ -71,8 +166,10 @@ export interface RoleplaySessionGetOpts extends CommonOpts {
     entryId?: string;
 }
 /**
- * The allowlist. Never the transcript, messages, contact name, graded snapshot, voice session,
- * recording or audio ids, or any video-evaluation field.
+ * The allowlist, shared by `roleplay session` and the manager view's scorecard. Never the transcript,
+ * messages, contact name, graded snapshot, voice session, recording or audio ids, or any
+ * video-evaluation field. The two scales (`grading_scale`, `max_score`) are numbers only (PIT-10068):
+ * legacy evaluations grade on 5, and a skill score is meaningless without its scale.
  */
 export declare function pickSessionDetail(id: string, data: Record<string, unknown>): Record<string, unknown>;
 export declare function runRoleplaySessionGet(opts: RoleplaySessionGetOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
@@ -81,5 +178,59 @@ export declare function pickScenario(s: Record<string, unknown>): Record<string,
 export declare function runRoleplayScenariosList(opts: CommonOpts & {
     instanceId?: string;
 }, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+export declare const ROLEPLAY_PATH_STATUSES: readonly ["published", "draft", "all"];
+export interface RoleplayPathRow {
+    id: string;
+    name: string;
+    status: string;
+    version: number;
+    stages: number;
+    steps: number;
+    default_passing_score: number | null;
+    updated_at: string | null;
+}
+/** The trimmed path: counts, never the stage/step bodies. */
+export declare function pickPath(p: Record<string, unknown>): RoleplayPathRow;
+/** next-core `GET roleplay/paths` (builder roles; 404 when paths are off or the caller is not a member). */
+export declare function fetchPaths(client: AxiosInstance, instanceId: string, status?: (typeof ROLEPLAY_PATH_STATUSES)[number]): Promise<Record<string, unknown>[]>;
+export declare function runRoleplayPathsList(opts: CommonOpts & {
+    instanceId?: string;
+    status?: string;
+}, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+/** next-core `GET roleplay/path-assignments`: the records in the caller's view (admins get the membership keys). */
+export declare function fetchPathRecords(client: AxiosInstance, instanceId: string): Promise<Record<string, unknown>[]>;
+export declare function postCoachComment(client: AxiosInstance, args: {
+    instanceId: string;
+    assignmentId: string;
+    repUserId: string;
+    sessionEntryId: string | null;
+    comment: string;
+}, idempotencyKey: string): Promise<{
+    body: {
+        id?: string;
+        data?: Record<string, unknown>;
+    };
+    replayed: boolean;
+}>;
+export declare function deleteCoachComment(client: AxiosInstance, args: {
+    instanceId: string;
+    commentId: string;
+}, idempotencyKey: string): Promise<{
+    replayed: boolean;
+}>;
+export declare function postPathAssignment(client: AxiosInstance, instanceId: string, body: {
+    pathId: string;
+    groupIds: string[];
+    recipientUserIds: string[];
+    managerIds: string[];
+    mandatory: boolean;
+    dueDate: string | null;
+}, idempotencyKey: string): Promise<{
+    body: {
+        record?: Record<string, unknown>;
+        warnings?: unknown[];
+    };
+    replayed: boolean;
+}>;
 export declare function createRoleplayCommand(): Command;
 export {};

package/dist/src/commands/roleplay.js

@@ -4,12 +4,12 @@ import { ok, fail } from '../core/envelope.js';
 import { createCliError, isCliError } from '../core/errors.js';
 import { emitEnvelope } from '../core/output.js';
 import { pageSizeFor } from '../core/analytics-shape.js';
-import { assignmentSessions, repStats, sessionScore, skillAverages, } from '../core/roleplay-stats.js';
+import { assignmentSessions, repStats, scaleOrNull, sessionScore, skillAverages, } from '../core/roleplay-stats.js';
 import { withAuthFlags } from './withAuth.js';
 export const ROLEPLAY_DIFFICULTIES = ['easy', 'medium', 'hard'];
 export const ROLEPLAY_SESSION_SORT = ['session_at', 'rep_name', 'score', 'duration_ms'];
 export const ROLEPLAY_GROUP_BY = ['rep', 'scenario'];
-const REP_STATUSES = ['passed', 'in_progress', 'not_started', 'overdue', 'needs_coaching'];
+export const REP_STATUSES = ['passed', 'in_progress', 'not_started', 'overdue', 'needs_coaching'];
 /** rep-summary reads at most this many pages of this size (5000 sessions), newest first. */
 export const REP_SUMMARY_PAGE_SIZE = 1000;
 export const REP_SUMMARY_MAX_PAGES = 5;
@@ -18,6 +18,11 @@ export const REP_SUMMARY_MAX_GROUPS = 50;
 export const COACH_DATA_SESSION_CAP = 1000;
 export const TEAM_MAX_ASSIGNMENTS = 50;
 export const TEAM_MAX_REPS_PER_ASSIGNMENT = 100;
+/**
+ * Pass progress (PIT-9971) is read in pages of 2000 (assignment, rep) pairs. Above this many pages the
+ * tools use no progress at all (the manager app allows 100,000 pages; one tool call stays bounded).
+ */
+export const PROGRESS_MAX_PAGES = 10;
 const COACH_BASE = '/core/api/protected/roleplay/coach';
 const APPSDB_QUERY = '/core/api/protected/appsdb/query';
 function requireInstance(opts, verb) {
@@ -47,7 +52,7 @@ function filterParams(opts, instanceId) {
 function windowOf(opts) {
     return { start_date: opts.startDate ?? null, end_date: opts.endDate ?? null };
 }
-const finiteOrNull = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+export const finiteOrNull = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
 /** clickhouse-api's roleplay routes are instance/org-admin only: say so, and where a manager goes instead. */
 function adminOnlyError(e) {
     const err = toCliError(e);
@@ -209,8 +214,15 @@ export async function runRoleplayRepSummary(opts, deps = {}) {
         return fail(adminOnlyError(e));
     }
 }
-async function getCoachBundle(client, instanceId) {
+/** `scopePref: 'coach'` skips the instance attempt; otherwise instance first, the caller's coaching scope on 403. */
+async function getCoachBundle(client, instanceId, scopePref) {
     const headers = { 'x-instance-id': instanceId };
+    const asCoach = async () => {
+        const res = await client.get(`${COACH_BASE}/data`, { params: { instance_id: instanceId }, headers });
+        return { bundle: (res.data ?? {}), requested: 'coach' };
+    };
+    if (scopePref === 'coach')
+        return asCoach();
     try {
         const res = await client.get(`${COACH_BASE}/data`, { params: { instance_id: instanceId, scope: 'instance' }, headers });
         return { bundle: (res.data ?? {}), requested: 'instance' };
@@ -219,14 +231,156 @@ async function getCoachBundle(client, instanceId) {
         // Not an instance or org admin: fall back to the caller's own coaching assignments.
         if (toCliError(e).code !== 'AUTH')
             throw e;
-        const res = await client.get(`${COACH_BASE}/data`, { params: { instance_id: instanceId }, headers });
-        return { bundle: (res.data ?? {}), requested: 'coach' };
+        return asCoach();
+    }
+}
+/** The caller's OWN coaching scope (coach/data without `scope`): what a coach may comment on (PIT-10113). */
+export async function getOwnCoachBundle(client, instanceId) {
+    return (await getCoachBundle(client, instanceId, 'coach')).bundle;
+}
+/** The manager app's progress map key (`useManagerData.ts`). */
+export const progressKey = (assignmentId, repUserId) => `${assignmentId}\u0000${repUserId}`;
+function toProgress(e) {
+    return {
+        passed: e.passed === true,
+        passSource: e.passSource === 'stored' || e.passSource === 'live' ? e.passSource : null,
+        attempts: typeof e.attempts === 'number' && Number.isFinite(e.attempts) ? e.attempts : 0,
+        bestScore: finiteOrNull(e.bestScore),
+        latestAt: typeof e.latestAt === 'string' ? e.latestAt : null,
+    };
+}
+const isProgressPage = (b) => Array.isArray(b.assignmentProgress) && !!b.assignmentProgressPage && typeof b.assignmentProgressPage.totalPairs === 'number';
+const PROGRESS_CHANGED = Symbol('progress-changed');
+/** Every page from 0, progress-only (`fetchAllProgressPages`, manager-app `lib/api.ts`). */
+async function fetchAllProgressPages(client, instanceId, scope) {
+    const out = [];
+    let total = null;
+    for (let page = 0; page < PROGRESS_MAX_PAGES; page += 1) {
+        const params = { instance_id: instanceId, assignment_page: page };
+        if (scope === 'instance')
+            params.scope = 'instance';
+        const res = await client.get(`${COACH_BASE}/data`, { params, headers: { 'x-instance-id': instanceId } });
+        const body = (res.data ?? {});
+        if (!isProgressPage(body))
+            throw new Error(`coach/data assignment_page=${page}: no progress in the answer`);
+        if (total !== null && body.assignmentProgressPage.totalPairs !== total)
+            return PROGRESS_CHANGED;
+        total = body.assignmentProgressPage.totalPairs;
+        out.push(...body.assignmentProgress);
+        if (!body.assignmentProgressPage.hasMore)
+            return out;
+    }
+    throw new Error(`coach/data: assignment progress has more than ${PROGRESS_MAX_PAGES} pages`);
+}
+const PROGRESS_LOST = 'Pass progress could not be loaded completely, so statuses, session counts and best scores come from the newest sessions only';
+/**
+ * `loadAssignmentProgress`: one page = the bundle's page 0 as is; more = every page from 0, progress-only
+ * with the APPLIED scope, restarted once if `totalPairs` changes; any failure, a second change or more
+ * than PROGRESS_MAX_PAGES pages = no progress (all-or-nothing). Absent progress is normal (empty bundle,
+ * older next-core, a server-side progress failure) and is not a warning.
+ */
+async function loadProgress(client, instanceId, bundle, scope, warnings) {
+    if (!isProgressPage(bundle))
+        return null;
+    const first = bundle.assignmentProgressPage;
+    let entries = null;
+    if (!first.hasMore)
+        entries = bundle.assignmentProgress;
+    else if (first.pageSize > 0 && Math.ceil(first.totalPairs / first.pageSize) > PROGRESS_MAX_PAGES)
+        entries = null;
+    else {
+        try {
+            const pass = await fetchAllProgressPages(client, instanceId, scope);
+            const again = pass === PROGRESS_CHANGED ? await fetchAllProgressPages(client, instanceId, scope) : pass;
+            entries = again === PROGRESS_CHANGED ? null : again;
+        }
+        catch {
+            entries = null;
+        }
+    }
+    if (!entries) {
+        warnings.push(PROGRESS_LOST);
+        return null;
+    }
+    const map = new Map();
+    for (const e of entries) {
+        if (typeof e.assignmentId !== 'string' || (typeof e.repUserId !== 'string' && typeof e.repUserId !== 'number'))
+            continue;
+        map.set(progressKey(e.assignmentId, String(e.repUserId)), toProgress(e));
+    }
+    return map;
+}
+/** D18 rep order: the reps who need the manager first. */
+export const STATUS_RANK = { overdue: 0, needs_coaching: 1, in_progress: 2, not_started: 3, passed: 4 };
+const cmpStr = (a, b) => (a ?? '').localeCompare(b ?? '', 'en');
+/** D18 assignment order: active first, then due date ascending (none last), then scenario name, then id. */
+export function compareAssignments(a, b) {
+    const active = Number(b.active !== false) - Number(a.active !== false);
+    if (active)
+        return active;
+    if (a.dueDate !== b.dueDate) {
+        if (!a.dueDate)
+            return 1;
+        if (!b.dueDate)
+            return -1;
+        return a.dueDate < b.dueDate ? -1 : 1;
     }
+    return cmpStr(a.scenarioName, b.scenarioName) || cmpStr(a.id, b.id);
+}
+/** D18 rep order: status rank, then name (no name last), then user id. */
+export function compareReps(a, b) {
+    const rank = STATUS_RANK[a.status] - STATUS_RANK[b.status];
+    if (rank)
+        return rank;
+    if (a.name !== b.name) {
+        if (a.name === null)
+            return 1;
+        if (b.name === null)
+            return -1;
+    }
+    return cmpStr(a.name, b.name) || cmpStr(a.user_id, b.user_id);
+}
+/**
+ * The one team derivation shared by `roleplay team` and the roleplay manager view (PIT-10068): the
+ * coach bundle, its pass progress, the roleplay filters and the D18 order, so the text tool and the
+ * view always cut the same 50 assignments.
+ */
+export async function loadTeamModel(client, instanceId, scopePref) {
+    const { bundle, requested } = await getCoachBundle(client, instanceId, scopePref);
+    // An older next-core ignores scope=instance and answers without `scope`: report what was applied.
+    const scope = bundle.scope === 'instance' && requested === 'instance' ? 'instance' : 'coach';
+    const sessions = (bundle.sessions ?? []).filter((s) => s.sessionType !== 'manager-video-practice');
+    const assignments = (bundle.assignments ?? []).filter((a) => a.contentType !== 'practice').sort(compareAssignments);
+    const warnings = [];
+    const sessionsCapped = sessions.length >= COACH_DATA_SESSION_CAP;
+    if (sessionsCapped) {
+        warnings.push(`The server returned its maximum of ${COACH_DATA_SESSION_CAP} sessions (newest first); older sessions are missing, so statuses and averages may be understated`);
+    }
+    const progress = await loadProgress(client, instanceId, bundle, scope, warnings);
+    let pairsWithoutProgress = 0;
+    if (progress) {
+        for (const a of assignments) {
+            for (const id of a.resolvedUserIds ?? [])
+                if (!progress.has(progressKey(a.id, id)))
+                    pairsWithoutProgress += 1;
+        }
+    }
+    return {
+        scope,
+        requested,
+        coverage: { sessionsCapped, progress: progress ? 'full' : 'none', pairsWithoutProgress },
+        warnings,
+        assignments,
+        sessions,
+        progress,
+    };
 }
 /**
  * Assignment completion per rep, ported from the manager app: an admin gets every roleplay
  * assignment on the instance (`scope=instance`), anyone else the assignments they coach.
- * Statuses follow `deriveStatus`; raw sessions, evaluations and comments never leave.
+ * Statuses, session counts and best scores follow `deriveStatus` / `repStats` with the server's
+ * pass progress when it loads (PIT-9971); assignments and reps in D18 order (`loadTeamModel`).
+ * Raw sessions, evaluations and comments never leave.
  */
 export async function runRoleplayTeam(opts, deps = {}) {
     try {
@@ -235,11 +389,9 @@ export async function runRoleplayTeam(opts, deps = {}) {
             throw createCliError('VALIDATION', `--status must be one of: ${REP_STATUSES.join(', ')}`);
         }
         const client = clientFor(opts, deps);
-        const { bundle, requested } = await getCoachBundle(client, instanceId);
-        // An older next-core ignores scope=instance and answers without `scope`: report what was applied.
-        const scope = bundle.scope === 'instance' && requested === 'instance' ? 'instance' : 'coach';
-        const sessions = (bundle.sessions ?? []).filter((s) => s.sessionType !== 'manager-video-practice');
-        const roleplayAssignments = (bundle.assignments ?? []).filter((a) => a.contentType !== 'practice');
+        const model = await loadTeamModel(client, instanceId);
+        const { scope, sessions, progress, coverage, warnings } = model;
+        const roleplayAssignments = model.assignments;
         const selected = opts.assignmentId ? roleplayAssignments.filter((a) => a.id === opts.assignmentId) : roleplayAssignments;
         if (opts.assignmentId && selected.length === 0) {
             throw createCliError('NOT_FOUND', `No roleplay assignment ${opts.assignmentId} in this ${scope === 'instance' ? 'instance' : 'coaching scope'}`);
@@ -248,10 +400,12 @@ export async function runRoleplayTeam(opts, deps = {}) {
         const shownAssignments = selected.slice(0, TEAM_MAX_ASSIGNMENTS);
         const assignments = shownAssignments.map((a) => {
             const own = assignmentSessions(sessions, a);
-            const reps = (a.resolvedUserIds ?? []).map((id) => ({
-                ...repStats(id, own, a, now),
+            const reps = (a.resolvedUserIds ?? [])
+                .map((id) => ({
+                ...repStats(id, own, a, now, progress?.get(progressKey(a.id, id)) ?? null),
                 name: a.resolvedUserNames?.[id] ?? null,
-            }));
+            }))
+                .sort(compareReps);
             const statusCounts = Object.fromEntries(REP_STATUSES.map((st) => [st, reps.filter((r) => r.status === st).length]));
             const filtered = opts.status ? reps.filter((r) => r.status === opts.status) : reps;
             const shownReps = filtered.slice(0, TEAM_MAX_REPS_PER_ASSIGNMENT);
@@ -273,14 +427,10 @@ export async function runRoleplayTeam(opts, deps = {}) {
                     : {}),
             };
         });
-        const capped = sessions.length >= COACH_DATA_SESSION_CAP;
-        const warnings = [];
-        if (capped) {
-            warnings.push(`The server returned its maximum of ${COACH_DATA_SESSION_CAP} sessions (newest first); older sessions are missing, so statuses and averages may be understated`);
-        }
         return ok({
             scope,
-            complete: !capped,
+            complete: !coverage.sessionsCapped,
+            coverage,
             assignments,
             total_assignments: selected.length,
             returned: assignments.length,
@@ -295,8 +445,10 @@ export async function runRoleplayTeam(opts, deps = {}) {
     }
 }
 /**
- * The allowlist. Never the transcript, messages, contact name, graded snapshot, voice session,
- * recording or audio ids, or any video-evaluation field.
+ * The allowlist, shared by `roleplay session` and the manager view's scorecard. Never the transcript,
+ * messages, contact name, graded snapshot, voice session, recording or audio ids, or any
+ * video-evaluation field. The two scales (`grading_scale`, `max_score`) are numbers only (PIT-10068):
+ * legacy evaluations grade on 5, and a skill score is meaningless without its scale.
  */
 export function pickSessionDetail(id, data) {
     const evaluation = (data.evaluation ?? null);
@@ -316,10 +468,12 @@ export function pickSessionDetail(id, data) {
                 summary: evaluation.summary ?? null,
                 strengths: Array.isArray(evaluation.strengths) ? evaluation.strengths : [],
                 improvements: Array.isArray(evaluation.improvements) ? evaluation.improvements : [],
+                grading_scale: scaleOrNull(evaluation.grading_scale),
                 category_scores: categories.map((c) => ({
                     skill_id: c.skillId ?? null,
                     title: c.title ?? null,
                     score: finiteOrNull(c.score),
+                    max_score: scaleOrNull(c.max_score),
                     feedback: c.feedback ?? null,
                 })),
             }
@@ -385,6 +539,97 @@ export async function runRoleplayScenariosList(opts, deps = {}) {
         return fail(toCliError(e));
     }
 }
+// ── learning paths (PIT-10113) ───────────────────────────────────────────────
+const PATHS_BASE = '/core/api/protected/roleplay/paths';
+const PATH_ASSIGNMENTS = '/core/api/protected/roleplay/path-assignments';
+export const ROLEPLAY_PATH_STATUSES = ['published', 'draft', 'all'];
+/** The trimmed path: counts, never the stage/step bodies. */
+export function pickPath(p) {
+    return {
+        id: String(p.id ?? ''),
+        name: typeof p.name === 'string' ? p.name : '',
+        status: typeof p.status === 'string' ? p.status : '',
+        version: typeof p.version === 'number' ? p.version : 0,
+        stages: Array.isArray(p.stages) ? p.stages.length : 0,
+        steps: Array.isArray(p.steps) ? p.steps.length : 0,
+        default_passing_score: finiteOrNull(p.defaultPassingScore),
+        updated_at: typeof p.updatedAt === 'string' ? p.updatedAt : null,
+    };
+}
+/** next-core `GET roleplay/paths` (builder roles; 404 when paths are off or the caller is not a member). */
+export async function fetchPaths(client, instanceId, status = 'published') {
+    const res = await client.get(PATHS_BASE, {
+        params: { instance_id: instanceId, status },
+        headers: { 'x-instance-id': instanceId },
+    });
+    const paths = res.data?.paths;
+    return Array.isArray(paths) ? paths : [];
+}
+export async function runRoleplayPathsList(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'paths');
+        const status = opts.status ?? 'published';
+        if (!ROLEPLAY_PATH_STATUSES.includes(status)) {
+            throw createCliError('VALIDATION', `--status must be one of ${ROLEPLAY_PATH_STATUSES.join(', ')}`);
+        }
+        const client = clientFor(opts, deps);
+        const paths = (await fetchPaths(client, instanceId, status)).map(pickPath);
+        return ok({ paths, total_count: paths.length });
+    }
+    catch (e) {
+        if (isCliError(e))
+            return fail(e);
+        const err = toCliError(e);
+        if (err.code === 'NOT_FOUND') {
+            return fail(createCliError('NOT_FOUND', 'Learning paths are not enabled on this instance, or you are not a member of it', err.backendStatus));
+        }
+        return fail(err);
+    }
+}
+/** next-core `GET roleplay/path-assignments`: the records in the caller's view (admins get the membership keys). */
+export async function fetchPathRecords(client, instanceId) {
+    const res = await client.get(PATH_ASSIGNMENTS, { params: { instance_id: instanceId }, headers: { 'x-instance-id': instanceId } });
+    const records = res.data?.records;
+    return Array.isArray(records) ? records : [];
+}
+// ── confirmed writes (PIT-10113): the three next-core calls, each with an Idempotency-Key ─────────────────────────
+/** A stored answer replayed by next-core: 200 with `Idempotent-Replay: true`. */
+function isReplay(res) {
+    const h = (res.headers ?? {});
+    const v = typeof h.get === 'function' ? h.get('idempotent-replay') : (h['idempotent-replay'] ?? h['Idempotent-Replay']);
+    return res.status === 200 && String(v).toLowerCase() === 'true';
+}
+export async function postCoachComment(client, args, idempotencyKey) {
+    const res = await client.post(`${COACH_BASE}/comments`, {
+        instanceId: args.instanceId,
+        sessionEntryId: args.sessionEntryId,
+        feedbackType: args.sessionEntryId ? 'session' : 'general',
+        assignmentId: args.assignmentId,
+        repUserId: args.repUserId,
+        comment: args.comment,
+        product: 'roleplay',
+    }, { headers: { 'x-instance-id': args.instanceId, 'Idempotency-Key': idempotencyKey } });
+    return { body: (res.data ?? {}), replayed: isReplay(res) };
+}
+export async function deleteCoachComment(client, args, idempotencyKey) {
+    const res = await client.delete(`${COACH_BASE}/comments/${encodeURIComponent(args.commentId)}`, {
+        params: { instance_id: args.instanceId },
+        headers: { 'x-instance-id': args.instanceId, 'Idempotency-Key': idempotencyKey },
+    });
+    return { replayed: isReplay(res) };
+}
+export async function postPathAssignment(client, instanceId, body, idempotencyKey) {
+    // exactly the six schema keys: the strict schema refuses any other (instance_id rides in the query)
+    const res = await client.post(PATH_ASSIGNMENTS, {
+        pathId: body.pathId,
+        groupIds: body.groupIds,
+        recipientUserIds: body.recipientUserIds,
+        managerIds: body.managerIds,
+        mandatory: body.mandatory,
+        dueDate: body.dueDate,
+    }, { params: { instance_id: instanceId }, headers: { 'x-instance-id': instanceId, 'Idempotency-Key': idempotencyKey } });
+    return { body: (res.data ?? {}), replayed: isReplay(res) };
+}
 // ── commander ────────────────────────────────────────────────────────────────
 const ADMIN_NOTE = 'instance or org admins only';
 function withFilterFlags(cmd) {
@@ -445,5 +690,13 @@ export function createRoleplayCommand() {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runRoleplayScenariosList({ ...options, quiet: globals.quiet }), globals);
     });
+    withAuthFlags(cmd.command('paths'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--status <status>', `Path status: ${ROLEPLAY_PATH_STATUSES.join(', ')} (default published)`)
+        .description('the instance learning paths: id, name, version, stage and step counts (instance admins and editors, org admins)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplayPathsList({ ...options, quiet: globals.quiet }), globals);
+    });
     return cmd;
 }