agentera 3.0.0-dev.8 → 3.0.0-dev.80

package/dist/cli/commands/profileGrounding.js

@@ -0,0 +1,55 @@
+import { personalProfileGroundingContract } from "../../registries/glossaryEntryContract.js";
+import { emitInvalidInput } from "../errors.js";
+import { acquireProfile } from "../profileAcquisition.js";
+import { emitStructured } from "../structured.js";
+const COMMAND = "agentera report profile-grounding --format json";
+const REQUEST_RECOVERY = `Run ${COMMAND}; no profile bytes were changed.`;
+const INVALID_PROFILE_MESSAGE = "PROFILE.md is unavailable for bounded profile grounding.";
+function invalid(io, body, recovery) {
+    return emitInvalidInput(io, { format: "json", body: { ...body, recovery } });
+}
+export function runProfileGroundingCommand(argv, io) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        const [name, inline] = argument.split("=", 2);
+        if (name !== "--format") {
+            return invalid(io, { class: "unrecognized_argument", message: "profile-grounding accepts only --format json", syntax: COMMAND }, REQUEST_RECOVERY);
+        }
+        const value = inline ?? argv[++index];
+        if (value !== "json") {
+            return invalid(io, { class: "invalid_choice", message: "profile-grounding requires --format json", valid_values: ["json"] }, REQUEST_RECOVERY);
+        }
+    }
+    const contract = personalProfileGroundingContract();
+    const acquired = acquireProfile();
+    const output = io.out ?? ((text) => process.stdout.write(text));
+    if (acquired.validity.status !== "valid" || acquired.groundingContent === null) {
+        emitStructured({
+            schemaVersion: contract.schemaVersion,
+            command: "report profile-grounding",
+            status: acquired.validity.status,
+            validity: acquired.validity,
+            freshness: acquired.freshness,
+            content: null,
+            recovery: acquired.validity.recovery,
+            error: {
+                class: "profile_unavailable",
+                message: INVALID_PROFILE_MESSAGE,
+                recovery: acquired.validity.recovery,
+            },
+        }, "json", output);
+        return 2;
+    }
+    emitStructured({
+        schemaVersion: contract.schemaVersion,
+        command: "report profile-grounding",
+        status: "ok",
+        validity: acquired.validity,
+        freshness: acquired.freshness,
+        content: acquired.groundingContent,
+        content_utf8_bytes: Buffer.byteLength(acquired.groundingContent),
+        excluded: "owned_personal_glossary_section",
+        recovery: null,
+    }, "json", output);
+    return 0;
+}

package/dist/cli/commands/query.js

@@ -1,12 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
-import { resolveArtifactPath } from "../../registries/artifactRegistry.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
+import { loadDocsPathOverrides, resolveArtifactPath, } from "../../registries/artifactRegistry.js";
 import { activeObjectiveName, artifactPath, discoverSchemasDir, loadSchemas, resolveArtifactPathLocal, } from "../appContext.js";
 import { validateAgentString } from "../argvalidate.js";
-import { loadDocsPathOverrides } from "../../registries/artifactRegistry.js";
 import { emitStructured } from "../structured.js";
-import { COMMAND_FILTERS, emitStateStructured, extractEntries, filterByFieldValue, filterByTopic, formatEntry, loadArtifact, missingSchemaError, recentCycles, sourceMetadata, structuredState, validateFilterValues, } from "../stateQuery.js";
+import { COMMAND_FILTERS, emitStateStructured, extractEntries, filterByFieldValue, filterByTopic, formatEntry, loadArtifact, missingSchemaError, sourceMetadata, structuredState, validateFilterValues, } from "../stateQuery.js";
 import { displayFields, queryTodo } from "./state/index.js";
+import { STATE_FAMILY_GET_COMMANDS, STATE_FAMILY_LIST_COMMANDS } from "../capabilityContext/types.js";
+import { entityPublicRetrieval } from "../../state/retrievalAuthority.js";
+import { listProgressEntities } from "../../state/progressEntities.js";
+import { readChangelog } from "../../state/changelog.js";
 const ENCODED_TRAVERSAL_RE = /%(?:2e|2f|5c)/i;
 const ALLOWED_RAW_ARTIFACT_USES = [
     "artifact writes",
@@ -17,7 +21,7 @@ const ALLOWED_RAW_ARTIFACT_USES = [
     "unavailable or incomplete CLI state after CLI fallbacks",
     "benchmark analysis",
 ];
-const BENCHMARK_CONTEXT_COMMAND = "agentera prime --context optimize --format json";
+const BENCHMARK_CONTEXT_COMMAND = preCutoverCommand("prime --context optimize --format json");
 const STATE_COMMAND_NAMES = new Set([
     "decisions",
     "docs",
@@ -43,7 +47,16 @@ function projectRelativeOrAbsolute(p) {
 }
 function artifactReadInterfaces(name, record) {
     const artifactId = record !== null ? record.artifactId : name;
-    const routineCommand = STATE_COMMAND_NAMES.has(artifactId) ? `agentera ${artifactId} --format json` : null;
+    const retrieval = (entityPublicRetrieval().commands ?? {});
+    const experimentList = retrieval.experiments.list
+        .replace(" [--limit N] [--cursor TOKEN]", " --limit 20");
+    const routineCommand = artifactId === "experiments"
+        ? experimentList
+        : STATE_FAMILY_LIST_COMMANDS[artifactId] ?? (STATE_COMMAND_NAMES.has(artifactId) ? `agentera state ${artifactId} --format json` : null);
+    const requiredSelectors = artifactId === "experiments" ? ["--objective OBJECTIVE_ID"] : [];
+    const detailCommand = artifactId === "experiments"
+        ? retrieval.experiments.get
+        : STATE_FAMILY_GET_COMMANDS[artifactId] ?? null;
     let advancedCommand;
     if (artifactId === "benchmark_context")
         advancedCommand = BENCHMARK_CONTEXT_COMMAND;
@@ -52,7 +65,11 @@ function artifactReadInterfaces(name, record) {
     else
         advancedCommand = `agentera query ${artifactId} --format json`;
     let policy;
-    if (routineCommand)
+    if (artifactId === "experiments")
+        policy = "Replace OBJECTIVE_ID with one stable objective identity, use the objective-scoped bounded list for discovery, and use exact get for detail; no selector-free normal read exists.";
+    else if (STATE_FAMILY_LIST_COMMANDS[artifactId])
+        policy = "Use bounded state list for discovery and exact state get for detail before any raw artifact access.";
+    else if (routineCommand)
         policy = "Use the routine state command for normal content reads before any raw artifact access.";
     else if (advancedCommand)
         policy = "Use the listed CLI discovery/query surface before any last-resort raw artifact access.";
@@ -60,6 +77,9 @@ function artifactReadInterfaces(name, record) {
         policy = "No normal content-read command is registered; raw access is limited to allowed boundary cases.";
     return {
         normal_read_command: routineCommand,
+        normal_read_required_selectors: requiredSelectors,
+        normal_detail_command: detailCommand,
+        normal_read_guidance: policy,
         advanced_query_command: advancedCommand,
         raw_access_boundary: {
             normal_policy: policy,
@@ -67,7 +87,7 @@ function artifactReadInterfaces(name, record) {
         },
     };
 }
-function artifactLocationRecord(name, info, schemasDir, docsOverrides) {
+function artifactLocationRecord(name, info, schemasDir) {
     const record = info.record ?? null;
     const schema = info.schema && typeof info.schema === "object" ? info.schema : {};
     // cast: schema.meta is read from a parsed artifact schema (YAML IO boundary)
@@ -76,13 +96,14 @@ function artifactLocationRecord(name, info, schemasDir, docsOverrides) {
     const artifactId = record !== null ? record.artifactId : name;
     const displayName = record !== null ? record.displayName : String(meta.name ?? name);
     const defaultPath = record !== null ? record.defaultPath : String(info.path ?? "");
-    let mappedPath = defaultPath;
-    let resolutionSource = record !== null ? "registry default" : "schema metadata";
+    const docsOverrides = record !== null ? loadDocsPathOverrides(process.cwd()) : {};
+    const mappedPath = record !== null && record.docsYamlCanOverridePath && record.displayName in docsOverrides
+        ? docsOverrides[record.displayName]
+        : defaultPath;
+    const resolutionSource = record !== null
+        ? mappedPath === defaultPath ? "registry default" : "docs mapping for registry identity"
+        : "schema metadata";
     const caveats = [];
-    if (record !== null && record.docsYamlCanOverridePath && record.displayName in docsOverrides) {
-        mappedPath = docsOverrides[record.displayName];
-        resolutionSource = ".agentera/docs.yaml mapping";
-    }
     const objectiveName = activeObjectiveName();
     let resolvedPath = null;
     if (record !== null && record.pathTemplate && mappedPath.includes("<name>") && !objectiveName) {
@@ -104,14 +125,15 @@ function artifactLocationRecord(name, info, schemasDir, docsOverrides) {
         display_path: resolvedPath !== null ? projectRelativeOrAbsolute(resolvedPath) : mappedPath,
         resolution_source: resolutionSource,
         exists: resolvedPath !== null ? fs.existsSync(resolvedPath) : false,
-        docs_yaml_can_override_path: record !== null ? record.docsYamlCanOverridePath : false,
+        docs_yaml_can_override_path: record?.docsYamlCanOverridePath ?? false,
         project_boundary_check: resolvedPath !== null ? "enforced" : "not_resolved",
     };
     return {
-        artifact_id: artifactId,
+        artifact: artifactId,
         name: artifactId,
         display_name: displayName,
         artifact_type: record !== null ? record.artifactType : meta.artifact_type ?? "unknown",
+        implementation_status: record !== null ? record.implementationStatus : meta.implementation_status ?? "implemented",
         format: typeof meta === "object" ? meta.format ?? "unknown" : "unknown",
         producer: record !== null ? [...record.producers].sort() : meta.producer ?? "unknown",
         consumers: record !== null ? [...record.consumers].sort() : meta.consumers ?? "unknown",
@@ -130,9 +152,8 @@ function fileExists(p) {
     }
 }
 export function artifactLocationContract(schemasDir, schemas) {
-    const docsOverrides = loadDocsPathOverrides(process.cwd());
     const names = Object.keys(schemas).sort();
-    const records = names.map((name) => artifactLocationRecord(name, schemas[name], schemasDir, docsOverrides));
+    const records = names.map((name) => artifactLocationRecord(name, schemas[name], schemasDir));
     // cast: record.caveats is built from schema/registry path resolution (IO boundary)
     const caveats = records.flatMap((record) => record.caveats);
     return {
@@ -140,8 +161,7 @@ export function artifactLocationContract(schemasDir, schemas) {
         status: dirExists(schemasDir) ? "complete" : "missing_schemas",
         source: {
             schemas_dir: schemasDir,
-            docs_yaml_path: path.join(process.cwd(), ".agentera", "docs.yaml"),
-            docs_yaml_overrides_loaded: Object.keys(docsOverrides).length > 0,
+            path_overrides: "disabled_for_entity_authority",
         },
         source_contract: {
             raw_artifact_reads_required_for_discovery: false,
@@ -213,30 +233,35 @@ function queryGeneric(args, schemas, name, io) {
     }
     return 0;
 }
-function queryLastPhase(args, schemas, io) {
-    const o = out(io);
-    const e = err(io);
+function matchedSchemaName(schemas, query) {
+    if (query in schemas)
+        return query;
+    return Object.keys(schemas).find((name) => query === name.replace(/s$/, "") || query === `${name}s`) ?? null;
+}
+function rejectEntityAggregateQuery(args, name, query, io) {
     const format = args.format ?? "text";
-    const info = schemas.progress;
-    if (!info) {
-        e(missingSchemaError("progress") + "\n");
-        return 1;
+    const command = `agentera state ${name} --format ${format}`;
+    if (format !== "text") {
+        emitStructured({ schemaVersion: "agentera.stateFailure.v1", status: "fail", error: { class: "unsupported_target", message: `routine artifact alias '${query}' is not available through state query`, syntax: command, example: command, recovery: `Use the canonical entity-aware command: ${command}` } }, format, out(io));
     }
-    const data = loadArtifact(artifactPath(info, "progress"));
-    const entries = extractEntries(data);
-    if (entries.length === 0) {
-        if (format !== "text")
-            emitStructured(null, format, o);
-        return 0;
+    else {
+        err(io)(`Unsupported routine query: ${query}. Use \`${command}\` instead.\n`);
     }
-    const last = recentCycles(entries, 1)[0];
-    const phase = last.phase ?? "";
-    if (format !== "text") {
-        emitStructured({ phase }, format, o);
-        return 0;
+    return 1;
+}
+function queryLastPhase(args, schemas, io) {
+    const o = out(io);
+    const format = args.format ?? "text";
+    const response = listProgressEntities(process.cwd(), 1, {}, undefined, { format: format });
+    const entry = Array.isArray(response.entries) ? response.entries[0] : undefined;
+    const record = entry?.record;
+    const phase = String(record?.phase ?? "");
+    if (format === "text") {
+        if (phase)
+            o(`${phase}\n`);
     }
-    if (phase)
-        o(phase + "\n");
+    else
+        emitStructured(entry ? { phase, id: entry.id, artifact: entry.artifact, provenance: entry.provenance, snapshot: response.snapshot, retrieval: { get: `agentera state progress get --id ${entry.id} --format json` } } : null, format, o);
     return 0;
 }
 function queryDesign(args, schemas, io) {
@@ -317,10 +342,6 @@ export function cmdQuery(args, io) {
     if (query.includes("/") || query.includes("\\") || query === "." || query === ".." || ENCODED_TRAVERSAL_RE.test(query)) {
         throw new Error(`unsupported artifact/query name ${pyRepr(query)}; path-like values are not artifact names`);
     }
-    if (STATE_COMMAND_NAMES.has(query)) {
-        e(`Unsupported routine query: ${query}. Use \`agentera ${query}\` instead.\n`);
-        return 1;
-    }
     const schemas = loadSchemas(discoverSchemasDir());
     const stateArgs = args;
     const handlers = {
@@ -329,16 +350,18 @@ export function cmdQuery(args, io) {
         "open-todos": (a, s, ioo) => queryTodo({ ...a, command: "todo" }, s, ioo, true),
     };
     if (query in handlers) {
-        if (format !== "text" && query in schemas)
-            return queryGeneric(args, schemas, query, io);
-        return handlers[query](args, schemas, io);
+        if (format === "text" || !(query in schemas))
+            return handlers[query](args, schemas, io);
     }
-    if (query in schemas)
-        return queryGeneric(args, schemas, query, io);
-    for (const name of Object.keys(schemas)) {
-        if (query === name || query === name.replace(/s$/, "") || query === name + "s") {
-            return queryGeneric(args, schemas, name, io);
+    const name = matchedSchemaName(schemas, query);
+    if (name !== null) {
+        if (STATE_COMMAND_NAMES.has(name)) {
+            return rejectEntityAggregateQuery(args, name, query, io);
+        }
+        if (name === "changelog" && format !== "text") {
+            return emitStateStructured(name, readChangelog(process.cwd()).projection, format, args.fields, o, e);
         }
+        return queryGeneric(args, schemas, name, io);
     }
     e(`Unknown query: ${query}\n`);
     return 1;
@@ -346,4 +369,3 @@ export function cmdQuery(args, io) {
 function pyRepr(value) {
     return value.includes("'") && !value.includes('"') ? `"${value}"` : `'${value}'`;
 }
-//# sourceMappingURL=query.js.map

package/dist/cli/commands/report.js

@@ -5,14 +5,23 @@ import { resolveProfileDirOverride, resolveXdgDataHome } from "../../core/envPat
 import { expanduser } from "../../core/paths.js";
 import { usageMain, corpusTooLargeReason } from "../../analytics/usageStats.js";
 import { extractCorpusMain } from "../../analytics/extractCorpus.js";
+import { acquirePersonalGlossaryRefreshCommitLock, PersonalGlossaryRefreshCommitLockError, produceCurrentPersonalGlossaryProjection, releasePersonalGlossaryRefreshCommitLock, } from "../../analytics/personalGlossaryRefreshProjection.js";
+import { tiersDirForCorpusPath, assessTiers, readBoundedMetadata, readCurrentGeneration, } from "../../analytics/extractCorpus/index.js";
 function buildExtractArgv(args, corpusPath) {
-    const argv = ["--output", corpusPath];
+    // Refresh publishes bounded evidence tiers to the directory co-located with
+    // the canonical corpus path (`<dir>/tiers`); the extract engine no longer
+    // accepts the monolithic `--output corpusPath` write target (tiers are the
+    // only canonical output). Passing `--tier-output` makes the displayed
+    // `corpus_path`/`tier_path` truthful: tiers land at `dirname(corpusPath)/tiers`.
+    const argv = ["--tier-output", tiersDirForCorpusPath(corpusPath)];
     for (const root of args.projectRoot ?? [])
         argv.push("--project-root", root);
     if (args.codexSessionsDir)
         argv.push("--codex-sessions-dir", args.codexSessionsDir);
     if (args.claudeProjectsDir)
         argv.push("--claude-projects-dir", args.claudeProjectsDir);
+    for (const source of args.importSources ?? [])
+        argv.push("--import-source", source);
     if (args.opencodeConversationsDir)
         argv.push("--opencode-conversations-dir", args.opencodeConversationsDir);
     if (args.copilotConversationsDir)
@@ -23,8 +32,6 @@ function buildExtractArgv(args, corpusPath) {
         argv.push("--cursor-chats-dir", args.cursorChatsDir);
     if (args.noCodex)
         argv.push("--no-codex");
-    if (args.noClaude)
-        argv.push("--no-claude");
     if (args.noOpencode)
         argv.push("--no-opencode");
     if (args.noCopilot)
@@ -38,7 +45,7 @@ function buildExtractArgv(args, corpusPath) {
     return argv;
 }
 function usageSyntax() {
-    return "agentera usage [--format text|json] [--corpus PATH] [--project VALUE]";
+    return "agentera usage [--format text|json] [--corpus PATH] [--project VALUE] [--sources active|all]";
 }
 function usageExample() {
     return "agentera usage --format json --project agentera";
@@ -73,30 +80,62 @@ export function statsCorpusPath(env = process.env, platform = process.platform)
 }
 /** Faithful port of `_stats_existing_corpus_status`. */
 export function statsExistingCorpusStatus(corpusPath) {
+    // Bounded tier path: when tiers are published, report readiness from the
+    // manifest + retained corpus metadata without reading full evidence. The
+    // documented `tier_state`/`tier_path` fields extend the legacy shape;
+    // existing `status`/`reason`/`extracted_at`/`total_records` are preserved.
+    const tiersDir = tiersDirForCorpusPath(corpusPath);
+    const assessment = assessTiers(tiersDir, corpusPath);
+    if (assessment.analyzable) {
+        const meta = readBoundedMetadata(tiersDir);
+        const manifest = meta.manifest;
+        const extractedAt = meta.corpusMetadata?.extracted_at ?? null;
+        return {
+            status: "ready",
+            path: corpusPath,
+            tier_path: tiersDir,
+            tier_state: assessment.state,
+            reason: "bounded evidence tier published",
+            extracted_at: extractedAt ?? (manifest?.published_at ?? null),
+            total_records: manifest?.total_records ?? 0,
+        };
+    }
+    if (assessment.state === "oversized" || assessment.state === "corrupt") {
+        return {
+            status: "stale",
+            path: corpusPath,
+            tier_path: tiersDir,
+            tier_state: assessment.state,
+            reason: assessment.recovery ?? `${assessment.state} evidence tier`,
+            ...(assessment.artifact ? { artifact: assessment.artifact } : {}),
+        };
+    }
+    // Legacy or missing: preserve the corpus-envelope status behavior.
     if (!fs.existsSync(corpusPath)) {
         return { status: "missing", path: corpusPath, reason: "corpus file does not exist" };
     }
     const tooLarge = corpusTooLargeReason(corpusPath);
     if (tooLarge) {
-        return { status: "stale", path: corpusPath, reason: tooLarge };
+        return { status: "stale", path: corpusPath, tier_state: "legacy", reason: tooLarge };
     }
     let data;
     try {
         data = JSON.parse(fs.readFileSync(corpusPath, "utf8"));
     }
     catch (exc) {
-        return { status: "stale", path: corpusPath, reason: `corpus is not readable JSON: ${exc.message}` };
+        return { status: "stale", path: corpusPath, tier_state: "legacy", reason: `corpus is not readable JSON: ${exc.message}` };
     }
     const records = data && typeof data === "object" && !Array.isArray(data) ? data.records ?? [] : [];
     const hasTurn = Array.isArray(records) &&
         records.some((r) => r && typeof r === "object" && r.source_kind === "conversation_turn");
     if (!hasTurn) {
-        return { status: "stale", path: corpusPath, reason: "corpus has no conversation_turn records" };
+        return { status: "stale", path: corpusPath, tier_state: "legacy", reason: "corpus has no conversation_turn records" };
     }
     const metadata = data.metadata && typeof data.metadata === "object" ? data.metadata : {};
     return {
         status: "ready",
         path: corpusPath,
+        tier_state: "legacy",
         reason: "existing corpus has conversation_turn records",
         extracted_at: metadata.extracted_at ?? null,
         total_records: records.length,
@@ -105,9 +144,9 @@ export function statsExistingCorpusStatus(corpusPath) {
 /**
  * Faithful port of scripts/agentera `cmd_stats` (canonical command is `report`;
  * `stats` is the deprecated alias and shares this logic). The plain read path
- * reuses the ported usage engine; corpus refresh (which would run the maintainer
- * extractor over local runtime history) is reported as unavailable in the
- * self-contained package.
+ * reuses the ported usage engine over bounded tiers (with a legacy
+ * corpus.json fallback when no tiers are published). `stats refresh` publishes
+ * bounded tiers from local runtime history under explicit consent.
  */
 export function cmdReport(args, io = {}) {
     const out = io.out ?? ((t) => process.stdout.write(t));
@@ -129,8 +168,24 @@ export function cmdReport(args, io = {}) {
             return 2;
         }
         if (!dryRun && consent !== "local-history") {
-            err("Error: agentera stats refresh requires explicit --consent local-history to read local runtime history. " +
-                "Preview first with agentera stats refresh --dry-run\n");
+            const recovery = "agentera report refresh --consent local-history";
+            const message = "Error: agentera stats refresh requires explicit --consent local-history to read local runtime history. " +
+                "Preview first with agentera stats refresh --dry-run";
+            if (outputFormat === "json") {
+                out(JSON.stringify({
+                    command: "stats refresh",
+                    status: "degraded_consent_required",
+                    recovery,
+                    privacy: {
+                        local_history_read: false,
+                        local_history_write: false,
+                        tier_write: false,
+                        required_consent: "local-history",
+                        provided_consent: consent,
+                    },
+                }, null, 2) + "\n");
+            }
+            err(`${message}\nRecovery: ${recovery}\n`);
             return 2;
         }
         const corpusPath = args.output || statsCorpusPath();
@@ -143,53 +198,157 @@ export function cmdReport(args, io = {}) {
                 privacy: {
                     local_history_read: false,
                     local_history_write: false,
-                    corpus_write: false,
+                    tier_write: false,
                     required_consent: "local-history",
                     provided_consent: null,
                 },
                 corpus_path: corpusPath,
+                tier_path: tiersDirForCorpusPath(corpusPath),
                 engine: { command: engineCommand },
                 diagnostics: [
-                    "dry-run does not read runtime history or write corpus files",
-                    "generated corpus is internal state for stats at $AGENTERA_PROFILE_DIR/intermediate/corpus.json",
+                    "dry-run does not read runtime history or write tier files",
+                    "published tiers are internal state for stats at $AGENTERA_PROFILE_DIR/intermediate/tiers",
+                    ...(args.importSources?.includes("claude")
+                        ? ["Claude historical import can contain secrets, file contents, and command output; apply stays local and read-only"]
+                        : []),
                 ],
             };
             if (outputFormat === "json") {
                 out(JSON.stringify(payload, null, 2) + "\n");
             }
             else {
-                out(`agentera stats refresh: dry_run\ncorpus=${corpusPath}\nengine=${engineCommand.join(" ")}\n`);
-                out("privacy=local_history_read=false, corpus_write=false, required_consent=local-history\n");
+                out(`agentera stats refresh: dry_run\ncorpus=${corpusPath}\ntiers=${tiersDirForCorpusPath(corpusPath)}\nengine=${engineCommand.join(" ")}\n`);
+                out("privacy=local_history_read=false, tier_write=false, required_consent=local-history\n");
             }
             return 0;
         }
-        // consent === "local-history": run the corpus extractor over local history.
+        // consent === "local-history": extract local history into bounded tiers.
+        const tiersDir = tiersDirForCorpusPath(corpusPath);
+        let refreshLock;
+        try {
+            refreshLock = acquirePersonalGlossaryRefreshCommitLock();
+        }
+        catch (error) {
+            if (!(error instanceof PersonalGlossaryRefreshCommitLockError))
+                throw error;
+            const recovery = error.recovery;
+            const currentGeneration = readCurrentGeneration(tiersDir);
+            const projection = {
+                status: "failed",
+                reason: error.message,
+                recovery,
+            };
+            const payload = {
+                command: "stats refresh",
+                status: "fail",
+                exit_signal: null,
+                privacy: {
+                    local_history_read: false,
+                    local_history_write: false,
+                    tier_write: false,
+                    projection_write: false,
+                    required_consent: "local-history",
+                    provided_consent: "local-history",
+                    historical_imports: args.importSources ?? [],
+                    historical_import_warning: args.importSources?.includes("claude")
+                        ? "Claude transcripts can contain secrets, file contents, and command output. Import is local and read-only."
+                        : null,
+                },
+                corpus_path: corpusPath,
+                tier_path: tiersDir,
+                evidence: {
+                    status: currentGeneration ? "readable" : "unavailable",
+                    ...(currentGeneration ? {
+                        generation: currentGeneration.manifest.generation,
+                        published_at: currentGeneration.manifest.published_at,
+                    } : {}),
+                },
+                projection,
+                engine: { command: engineCommand, exit_code: null, stdout: [], stderr: [] },
+            };
+            if (outputFormat === "json") {
+                out(JSON.stringify(payload, null, 2) + "\n");
+            }
+            else {
+                out(`agentera stats refresh: fail\ncorpus=${corpusPath}\ntiers=${tiersDir}\n`);
+                err(`candidate projection failed: ${projection.reason}\nRecovery: ${recovery}\n`);
+            }
+            return 1;
+        }
         let engineOut = "";
         let engineErr = "";
-        const rc = extractCorpusMain(engineArgv, {
-            out: (t) => (engineOut += t + "\n"),
-            err: (t) => (engineErr += t + "\n"),
-        });
-        const refreshStatus = rc === 0 ? "pass" : rc === 4 ? "flagged" : "fail";
+        let rc;
+        let projection = { status: "not_attempted" };
+        let finalRc;
+        let currentGeneration;
+        try {
+            rc = extractCorpusMain(engineArgv, {
+                out: (t) => (engineOut += t + "\n"),
+                err: (t) => (engineErr += t + "\n"),
+            });
+            finalRc = rc;
+            currentGeneration = rc === 0 ? readCurrentGeneration(tiersDir) : null;
+            if (rc === 0) {
+                try {
+                    const produced = produceCurrentPersonalGlossaryProjection({ tiersDir });
+                    projection = { ...produced, write_status: produced.status, status: "published" };
+                }
+                catch (error) {
+                    finalRc = 1;
+                    projection = {
+                        status: "failed",
+                        reason: error.message,
+                        recovery: "npx -y agentera@next report refresh --consent local-history",
+                    };
+                }
+            }
+        }
+        finally {
+            releasePersonalGlossaryRefreshCommitLock(refreshLock);
+        }
+        const refreshStatus = finalRc === 0 ? "pass" : rc === 4 ? "flagged" : "fail";
         const payload = {
             command: "stats refresh",
             status: refreshStatus,
             exit_signal: rc === 4 ? "EX2" : null,
-            privacy: { local_history_read: true, local_history_write: false, corpus_write: rc === 0, required_consent: "local-history", provided_consent: "local-history" },
+            privacy: {
+                local_history_read: true,
+                local_history_write: false,
+                tier_write: rc === 0,
+                projection_write: projection.status === "published",
+                required_consent: "local-history",
+                provided_consent: "local-history",
+                historical_imports: args.importSources ?? [],
+                historical_import_warning: args.importSources?.includes("claude")
+                    ? "Claude transcripts can contain secrets, file contents, and command output. Import is local and read-only."
+                    : null,
+            },
             corpus_path: corpusPath,
+            tier_path: tiersDir,
+            evidence: {
+                status: rc === 0 ? "published" : "failed",
+                ...(currentGeneration ? {
+                    generation: currentGeneration.manifest.generation,
+                    published_at: currentGeneration.manifest.published_at,
+                } : {}),
+            },
+            projection,
             engine: { command: engineCommand, exit_code: rc, stdout: engineOut.split("\n").filter((l) => l), stderr: engineErr.split("\n").filter((l) => l) },
         };
         if (outputFormat === "json") {
             out(JSON.stringify(payload, null, 2) + "\n");
         }
         else {
-            out(`agentera stats refresh: ${payload.status}\ncorpus=${corpusPath}\n`);
+            out(`agentera stats refresh: ${payload.status}\ncorpus=${corpusPath}\ntiers=${tiersDirForCorpusPath(corpusPath)}\n`);
             if (engineOut)
                 out(engineOut);
             if (engineErr)
                 err(engineErr);
+            if (projection.status === "failed") {
+                err(`candidate projection failed: ${String(projection.reason)}\nRecovery: ${String(projection.recovery)}\n`);
+            }
         }
-        return rc;
+        return finalRc;
     }
     if (action !== null) {
         err(`Error: unsupported stats action '${action}'. ` +
@@ -221,6 +380,8 @@ export function cmdReport(args, io = {}) {
     const engineArgs = ["--corpus", corpusPath];
     if (args.project)
         engineArgs.push("--project", args.project);
+    if (args.sources)
+        engineArgs.push("--sources", args.sources);
     if (outputFormat === "json")
         engineArgs.push("--json");
     return usageMain(engineArgs, {
@@ -228,4 +389,3 @@ export function cmdReport(args, io = {}) {
         err: (t) => err(t + "\n"),
     });
 }
-//# sourceMappingURL=report.js.map