agentera 3.0.0-dev.76 → 3.0.0-dev.78

package/bundle/skills/agentera/schemas/artifacts/plan.yaml

@@ -7,40 +7,7 @@
 # The active authority uses one plan or plan_task entity per writer-owned file.
 # The aggregate model below is the complete atomic plan-create input. Its task
 # numbers and numeric/string dependency references are create-local symbols,
-# not persisted identities. Fields explicitly labeled migration-only remain
-# compatibility input and are not ordinary post-cutover entity contracts.
-#
-# ── Legacy migration-input mapping: v1 PLAN.md → v2 plan.yaml ──
-#
-# The ordinal task fields in this mapping are create-local symbolic references.
-# They are valid only inside one atomic `state plan create --input` document and
-# are removed when the writer publishes plan and plan_task entities.
-#
-# v1 Field                              v2 Field               v2 ID
-# ─────────────────────────────────────────────────────────────────────
-# <!-- Level: light/full -->            HEADER.level           PL1
-# <!-- Created: date -->                HEADER.created         PL2
-# <!-- Status: active/completed -->     HEADER.status          PL3 (normalized)
-# <!-- Reviewed: date -->               HEADER.reviewed        PL4
-# <!-- Critic issues: N found... -->    HEADER.critic_issues   PL5
-# <!-- Revised: description -->         HEADER.revised         PL6
-# # Plan: <title>                       HEADER.title           PL7
-# ## What                               PLAN.what              PL8
-# ## Why                                PLAN.why               PL9
-# ## Constraints                        PLAN.constraints       PL10
-# ## Scope / **In**: <list>             SCOPE.included         PL11
-# ## Scope / **Out**: <list>            SCOPE.excluded         PL12
-# ## Scope / **Deferred**: <list>       SCOPE.deferred         PL13
-# ## Design                             PLAN.design            PL14
-# ### Task N: <name>                    TASK.number            PL15 (create-local only)
-# (task name from heading)              TASK.name              PL16
-# **Depends on**: <text>                TASK.depends_on        PL17
-# **Status**: <status>                  TASK.status            PL18
-# **Acceptance**: <criteria list>       TASK.acceptance        PL19
-# ## Overall Acceptance                 PLAN.overall_acceptance PL20
-# ## Surprises                          PLAN.surprises         PL21
-# ## Unknowns                           UNKNOWN.entry          PU1
-# ## Rejected Review Findings           REJECTED.entry         PR1
+# not persisted identities.
 #
 # Protocol references:
 #   status visual tokens: VT1-VT4 (protocol.yaml VISUAL_TOKENS)
@@ -726,7 +693,6 @@ LIFECYCLE_CONTRACT:
       - packages/cli/src/upgrade/migrateArtifacts*.ts
       - packages/cli/src/upgrade/upgradeOrchestrator.ts
       - packages/cli/src/upgrade/doctor.ts
-      - packages/cli/src/cli/commands/prime/v1Migration.ts
       - packages/cli/src/state/entityMigration*.ts
       - packages/cli/src/state/canonicalMigrationRecord.ts
     schemas:

package/bundle/skills/agentera/schemas/artifacts/progress.yaml

@@ -10,31 +10,7 @@
 # bounded current writer intent for Build and never delivers or persists it in
 # plan state. Prime projects generic review attention without lifecycle details.
 #
-# The active authority is one progress_cycle entity per writer-owned file. The
-# numbered projection model below is retained only as an exact legacy migration
-# input schema; it is not an ordinary read or write contract after cutover.
-#
-# ── Field-by-field mapping: v1 PROGRESS.md → v2 progress.yaml ──
-#
-# v1 Field                              v2 Field               v2 ID
-# ─────────────────────────────────────────────────────────────────────
-# ## Cycle N · date · type-prefix       CYCLE.number           PR1
-# (date from heading)                   CYCLE.timestamp        PR2
-# (type-prefix from heading)            CYCLE.type             PR3
-# **Phase**: <phase>                    CYCLE.phase            PR4
-# **What**: <text>                      CYCLE.what             PR5
-# **Inspiration**: <text>               CYCLE.inspiration      PR6
-# **Discovered**: <text>                CYCLE.discovered       PR7
-# **Verified**: <text>                  CYCLE.verified         PR8
-# **Next**: <text>                      CYCLE.next             PR9
-# **Context**: <text>                   CYCLE.context          PR10
-# (intent from Context)                 CONTEXT.intent         PT1
-# (constraints from Context)            CONTEXT.constraints    PT2
-# (unknowns from Context)               CONTEXT.unknowns       PT3
-# (scope from Context)                  CONTEXT.scope          PT4
-# ## Archived Cycles                    (implicit section)     —
-# - Cycle N (date): summary            ARCHIVE.summary        PA1
-#
+# The active authority is one progress_cycle entity per writer-owned file.
 # Protocol references:
 #   phase: PH1-PH5 (protocol.yaml PHASES)
 #   type: conventional commit prefix (feat/fix/docs/refactor/chore/test)

package/bundle/skills/agentera/schemas/artifacts/vision.yaml

@@ -7,25 +7,6 @@
 # Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
 # following capability_schema_contract.yaml and protocol.yaml conventions.
 #
-# ── Field-by-field mapping: v1 VISION.md → v2 vision.yaml ──
-#
-# v1 Field                              v2 Field               v2 ID
-# ─────────────────────────────────────────────────────────────────────
-# # <project name>                       HEADER.project_name    VN1
-# ## North Star                          NORTH_STAR.content     VN2
-# ## Who It's For / ### persona name     PERSONA.entry          VN3
-# (persona heading)                      PERSONA.name           VN4
-# (persona prose)                        PERSONA.description    VN5
-# ## Principles / - principle            PRINCIPLE.entry        VN6
-# (bold name + description)              PRINCIPLE.name         VN7
-# (principle prose)                      PRINCIPLE.description  VN8
-# ## Direction                           DIRECTION.content      VN9
-# ## Identity / ### Personality          IDENTITY.personality   VN10
-# ## Identity / ### Voice                IDENTITY.voice         VN11
-# ## Identity / ### Emotional register   IDENTITY.emotional_register VN12
-# ## Identity / ### Naming               IDENTITY.naming        VN13
-# ## The Tension                         TENSION.content        VN14
-#
 # Protocol references:
 #   No protocol primitives directly. Vision defines project-level identity
 #   that capabilities reference for voice and personality consistency.

package/dist/.agentera-build-source.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "agentera.generatedBuildSource.v1",
-  "commit": "70aed21badb985087fd79371fabb61b1ec31ddde",
-  "tree": "3baa4c8145944638cad38ae98346f98518d01884",
-  "files": 6750,
-  "workingTreeSha256": "57aa3b7d804724356e7a3bf9adf7ea9a54e29312cd19b0abcd23f4f9699dfe54",
-  "identitySha256": "f4acdd4621fd8110b1277f88be7f093929a887c6b4db6c3269e3a1af98a63b36"
+  "commit": "eb1d15be07e52525a9b2bd30590e996bb42dc463",
+  "tree": "4d8d697897d1186193da51ea43e66f9fa6adebf1",
+  "files": 6835,
+  "workingTreeSha256": "b114aced044d84f4f9657fe213d1e7db99e564e7d205e3453c09499f4ddb3893",
+  "identitySha256": "0692b08db944d0d52a32b08bc71713338482717eee5bf79eb64215a96e1ca9d0"
 }

package/dist/analytics/personalGlossaryAdmission.js

@@ -108,6 +108,6 @@ export function admitPersonalGlossaryEvidence(input, resolveAnchor = resolveEvid
 }
 export { classifyExplicitGlossaryLanguage, discoverExplicitGlossaryCues, mineExplicitGlossaryCandidates, mineExplicitGlossaryEvidence, minePersonalExplicitGlossaryCandidates, EXPLICIT_GLOSSARY_REASONS, } from "./personalGlossaryExplicit.js";
 export { mineRecurringGlossaryCandidates, mineRecurringGlossaryEvidence, PERSONAL_GLOSSARY_MINING_POLICY_VERSION, RECURRING_MEANING_PENDING_REVIEW, RECURRING_REASONS, } from "./personalGlossaryRecurrence.js";
-export { maintainPersonalGlossaryCandidateProjection, personalGlossaryCandidateProjectionPath, personalGlossaryProjectionProjectIdentity, persistPersonalGlossaryCandidateProjection, projectPersonalGlossaryCandidates, readPersonalGlossaryCandidateProjection, } from "./personalGlossaryCandidateProjection.js";
+export { maintainPersonalGlossaryCandidateProjection, personalGlossaryCandidateProjectionPath, personalGlossaryProjectionProjectIdentity, persistPersonalGlossaryCandidateProjection, persistPersonalGlossaryCandidateProjectionAfterRefresh, projectPersonalGlossaryCandidates, readPersonalGlossaryCandidateProjection, } from "./personalGlossaryCandidateProjection.js";
 export { decidePersonalGlossaryCandidate, } from "./personalGlossaryDecision.js";
 export { currentPersonalGlossaryReviewRecords, maintainPersonalGlossaryReviewRecords, personalGlossaryReviewRecordsPath, queuePersonalGlossaryReviewRecord, readPersonalGlossaryReviewRecords, } from "./personalGlossaryReviewRecords.js";

package/dist/analytics/personalGlossaryCandidateProjection.js

@@ -7,6 +7,7 @@ import { defaultProfileDir } from "./extractCorpus/core.js";
 import { EXCERPT_OMISSION_REASONS, containsPersonalGlossarySensitiveContent, personalGlossaryCandidateProjectionExcerptExpiry, selectPersonalGlossarySafeExcerpt, validPersonalGlossarySafeExcerpt, } from "./personalGlossaryCandidateProjectionExcerpts.js";
 const PROJECTION_SCHEMA_VERSION = "agentera.personalGlossaryCandidateProjection.v1";
 const PROJECTION_REPORT_SCHEMA_VERSION = "agentera.personalGlossaryCandidateProjectionReport.v1";
+const MINING_SUMMARY_SCHEMA_VERSION = "agentera.personalGlossaryMiningSummary.v1";
 const PROJECT_IDENTITY_SCHEMA_VERSION = "agentera.personalGlossaryProjectionProjectIdentity.v1";
 const PROJECTION_OWNER = "deterministic_discovery_projection";
 const SHA256_RE = /^[a-f0-9]{64}$/u;
@@ -50,6 +51,9 @@ function projectionContract() {
         contract.storageFile !== "candidate-projection.json" ||
         contract.candidateSecretReason !== "secret_content" ||
         contract.excerptSensitiveContentAction !== "omit_complete_excerpt_before_projection" ||
+        contract.miningSummarySchemaVersion !== MINING_SUMMARY_SCHEMA_VERSION ||
+        contract.explicitAbstentionKeys.length !== 24 ||
+        contract.recurringAbstentionKeys.length !== 12 ||
         JSON.stringify(Object.keys(families)) !== JSON.stringify(["explicit", "recurring"]) ||
         JSON.stringify(families.explicit) !== JSON.stringify(["personal_explicit_definition"]) ||
         JSON.stringify(families.recurring) !==
@@ -58,6 +62,61 @@ function projectionContract() {
     }
     return contract;
 }
+function zeroReasons(keys) {
+    return Object.fromEntries(keys.map((key) => [key, 0]));
+}
+function projectionMiningSummary(input, contract) {
+    if (input.mining_summary)
+        return input.mining_summary;
+    let explicit = 0;
+    let recurring = 0;
+    for (const candidate of input.candidates) {
+        if (candidate.capsule.provenance_kind === "personal_explicit_definition")
+            explicit += 1;
+        else
+            recurring += 1;
+    }
+    return {
+        schema_version: MINING_SUMMARY_SCHEMA_VERSION,
+        explicit: {
+            candidate_count: explicit,
+            abstention_count: 0,
+            abstentions_by_reason: zeroReasons(contract.explicitAbstentionKeys),
+        },
+        recurring: {
+            candidate_count: recurring,
+            abstention_count: 0,
+            abstentions_by_reason: zeroReasons(contract.recurringAbstentionKeys),
+        },
+        total_candidate_count: explicit + recurring,
+        total_abstention_count: 0,
+    };
+}
+function validMiningFamily(value, keys) {
+    const family = mapping(value);
+    const reasons = mapping(family?.abstentions_by_reason);
+    return family !== null && reasons !== null &&
+        exactKeys(family, ["candidate_count", "abstention_count", "abstentions_by_reason"]) &&
+        nonNegativeInteger(family.candidate_count) && nonNegativeInteger(family.abstention_count) &&
+        exactKeys(reasons, keys) && Object.values(reasons).every(nonNegativeInteger) &&
+        family.abstention_count === Object.values(reasons).reduce((sum, count) => sum + Number(count), 0);
+}
+function validMiningSummary(value, inputCount, contract) {
+    const summary = mapping(value);
+    if (summary === null || !exactKeys(summary, [
+        "schema_version", "explicit", "recurring", "total_candidate_count", "total_abstention_count",
+    ]) || summary.schema_version !== MINING_SUMMARY_SCHEMA_VERSION ||
+        !validMiningFamily(summary.explicit, contract.explicitAbstentionKeys) ||
+        !validMiningFamily(summary.recurring, contract.recurringAbstentionKeys) ||
+        !nonNegativeInteger(summary.total_candidate_count) ||
+        !nonNegativeInteger(summary.total_abstention_count))
+        return false;
+    const explicit = summary.explicit;
+    const recurring = summary.recurring;
+    return summary.total_candidate_count === explicit.candidate_count + recurring.candidate_count &&
+        summary.total_candidate_count === inputCount &&
+        summary.total_abstention_count === explicit.abstention_count + recurring.abstention_count;
+}
 function sourceFamily(capsule, contract) {
     const matches = Object.entries(contract.sourceFamilies)
         .filter(([, kinds]) => kinds.includes(capsule.provenance_kind))
@@ -218,6 +277,10 @@ export function projectPersonalGlossaryCandidates(input) {
     if (!Array.isArray(input.candidates)) {
         throw new TypeError("projection candidates must be a list");
     }
+    const miningSummary = projectionMiningSummary(input, contract);
+    if (!validMiningSummary(miningSummary, input.candidates.length, contract)) {
+        throw new TypeError("candidate mining summary is invalid");
+    }
     const merged = mergeCandidates(input, contract);
     const selected = selectCandidates(merged.candidates, contract);
     const availableByFamily = countByFamily(merged.candidates);
@@ -295,6 +358,7 @@ export function projectPersonalGlossaryCandidates(input) {
             expired: 0,
             omissions,
         },
+        mining_summary: miningSummary,
     };
     const projection = {
         schema_version: PROJECTION_SCHEMA_VERSION,
@@ -378,6 +442,7 @@ function validProjectionReport(value) {
             "projects",
             "coverage",
             "excerpts",
+            "mining_summary",
         ]) ||
         report.schema_version !== PROJECTION_REPORT_SCHEMA_VERSION ||
         ![
@@ -415,6 +480,7 @@ function validProjectionReport(value) {
         !Array.isArray(coverage.uncovered_source_families) ||
         coverage.uncovered_source_families.some((family) => family !== "explicit" && family !== "recurring") ||
         !nonNegativeInteger(coverage.uncovered_projects) ||
+        !validMiningSummary(report.mining_summary, Number(report.input_count), projectionContract()) ||
         excerpts === null ||
         !exactKeys(excerpts, [
             "provided",
@@ -645,6 +711,36 @@ export function persistPersonalGlossaryCandidateProjection(projection, options =
     privateWrite(pathname, text);
     return { status: "changed", path: pathname };
 }
+/** Persist after explicit refresh consent, replacing only a malformed owned regular file. */
+export function persistPersonalGlossaryCandidateProjectionAfterRefresh(projection, options = {}) {
+    if (!validProjection(projection))
+        throw new TypeError("candidate projection is invalid");
+    const pathname = personalGlossaryCandidateProjectionPath(options);
+    const root = path.resolve(defaultProfileDir(options.env ?? process.env, options.platform ?? process.platform), "intermediate", "personal-glossary");
+    if (path.resolve(pathname) !== path.join(root, projectionContract().storageFile)) {
+        throw new TypeError("candidate projection path escapes its configured storage root");
+    }
+    try {
+        const metadata = fs.lstatSync(pathname);
+        if (metadata.isSymbolicLink() || !metadata.isFile()) {
+            throw new TypeError("candidate projection replacement requires the exact regular file");
+        }
+        const text = `${canonicalGlossaryJson(projection)}\n`;
+        const current = readPersonalGlossaryCandidateProjection(options);
+        if (current.status === "current" && fs.readFileSync(pathname, "utf8") === text) {
+            ensurePrivateProjectionMode(pathname);
+            return { status: "unchanged_replay", path: pathname };
+        }
+        privateWrite(pathname, text);
+        return { status: "changed", path: pathname };
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    privateWrite(pathname, `${canonicalGlossaryJson(projection)}\n`);
+    return { status: "changed", path: pathname };
+}
 /**
  * Apply only expiry or a local-host-authorized purge to the private projection.
  * No CLI command exposes this primitive. The later review lifecycle owns the

package/dist/analytics/personalGlossaryCandidateProjectionModel.js

@@ -0,0 +1 @@
+export {};

package/dist/analytics/personalGlossaryRefreshProjection.js

@@ -0,0 +1,351 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { personalGlossaryCandidateProjectionContract } from "../registries/glossaryCandidateProjectionContract.js";
+import { PERSONAL_GLOSSARY_MINING_POLICY_VERSION } from "../registries/glossaryMiningAuthority.js";
+import { readCurrentGeneration } from "./extractCorpus/evidenceTiers.js";
+import { mineExplicitGlossaryCandidates } from "./personalGlossaryExplicitMining.js";
+import { mineRecurringGlossaryCandidates } from "./personalGlossaryRecurrence.js";
+import { personalGlossaryCandidateProjectionPath, persistPersonalGlossaryCandidateProjectionAfterRefresh, projectPersonalGlossaryCandidates, } from "./personalGlossaryCandidateProjection.js";
+const LOCK_SCHEMA_VERSION = "agentera.personalGlossaryRefreshLock.v1";
+const MAX_LOCK_BYTES = 8 * 1024;
+const FILE_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0);
+const TOKEN_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+export class PersonalGlossaryRefreshCommitLockError extends Error {
+    recovery;
+    constructor(message, recovery) {
+        super(message);
+        this.recovery = recovery;
+        this.name = "PersonalGlossaryRefreshCommitLockError";
+    }
+}
+export class PersonalGlossaryRefreshCommitBusyError extends PersonalGlossaryRefreshCommitLockError {
+    constructor(message = "another consented refresh is still publishing the current candidate projection") {
+        super(message, "npx -y agentera@next report refresh --consent local-history");
+        this.name = "PersonalGlossaryRefreshCommitBusyError";
+    }
+}
+function unsafeLock(lockPath, detail) {
+    throw new PersonalGlossaryRefreshCommitLockError(`personal glossary refresh lock is unsafe: ${detail}`, `Inspect ${lockPath}; remove it only after verifying no refresh owns it, then rerun npx -y agentera@next report refresh --consent local-history`);
+}
+function identity(fd) {
+    const stat = fs.fstatSync(fd, { bigint: true });
+    return { dev: stat.dev, ino: stat.ino };
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sameRecord(left, right) {
+    return left.schema_version === right.schema_version
+        && left.pid === right.pid
+        && left.token === right.token
+        && left.created_at === right.created_at;
+}
+function parseRecord(value) {
+    if (value === null
+        || typeof value !== "object"
+        || value.schema_version !== LOCK_SCHEMA_VERSION
+        || !Number.isSafeInteger(value.pid)
+        || value.pid <= 0
+        || typeof value.token !== "string"
+        || !TOKEN_PATTERN.test(value.token)
+        || typeof value.created_at !== "string"
+        || !Number.isFinite(Date.parse(value.created_at)))
+        return null;
+    return value;
+}
+function readRecord(fd) {
+    try {
+        const stat = fs.fstatSync(fd, { bigint: true });
+        if (!stat.isFile() || stat.size === 0n || stat.size > BigInt(MAX_LOCK_BYTES))
+            return null;
+        const bytes = Buffer.alloc(Number(stat.size));
+        let offset = 0;
+        while (offset < bytes.length) {
+            const count = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+            if (count === 0)
+                return null;
+            offset += count;
+        }
+        return parseRecord(JSON.parse(bytes.toString("utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+function openOwnedRecord(recordPath, label) {
+    let stat;
+    try {
+        stat = fs.lstatSync(recordPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (stat.isSymbolicLink())
+        unsafeLock(recordPath, `${label} is a symbolic link`);
+    if (!stat.isFile())
+        unsafeLock(recordPath, `${label} is not a regular file`);
+    let descriptor;
+    try {
+        descriptor = fs.openSync(recordPath, FILE_FLAGS);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            unsafeLock(recordPath, `${label} changed during inspection`);
+        throw error;
+    }
+    const opened = fs.fstatSync(descriptor);
+    if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino) {
+        fs.closeSync(descriptor);
+        unsafeLock(recordPath, `${label} changed identity during inspection`);
+    }
+    const record = readRecord(descriptor);
+    if (!record) {
+        fs.closeSync(descriptor);
+        unsafeLock(recordPath, `${label} has a malformed or foreign ownership record`);
+    }
+    return { descriptor, record };
+}
+function ownerState(pid) {
+    if (pid === process.pid)
+        return "live";
+    try {
+        process.kill(pid, 0);
+        return "live";
+    }
+    catch (error) {
+        return error.code === "ESRCH" ? "dead" : "indeterminate";
+    }
+}
+function pathMatches(pathname, descriptor) {
+    let observed;
+    try {
+        observed = fs.openSync(pathname, FILE_FLAGS);
+        return sameIdentity(identity(observed), identity(descriptor));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (observed !== undefined)
+            fs.closeSync(observed);
+    }
+}
+function unlinkOwned(pathname, descriptor) {
+    if (!pathMatches(pathname, descriptor))
+        return false;
+    try {
+        fs.unlinkSync(pathname);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function prepareRecord(directory, basename, record) {
+    const preparedPath = path.join(directory, `.${basename}.${record.token}.tmp`);
+    const descriptor = fs.openSync(preparedPath, fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    try {
+        fs.writeFileSync(descriptor, `${JSON.stringify(record)}\n`);
+        fs.fsyncSync(descriptor);
+        return { path: preparedPath, descriptor };
+    }
+    catch (error) {
+        fs.closeSync(descriptor);
+        fs.rmSync(preparedPath, { force: true });
+        throw error;
+    }
+}
+function publishPrepared(prepared, targetPath) {
+    try {
+        fs.linkSync(prepared.path, targetPath);
+        try {
+            fs.unlinkSync(prepared.path);
+        }
+        catch (error) {
+            unlinkOwned(targetPath, prepared.descriptor);
+            throw error;
+        }
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+}
+function removeDeadClaim(claimPath) {
+    const claim = openOwnedRecord(claimPath, "reclaim claim");
+    if (!claim)
+        return;
+    try {
+        const state = ownerState(claim.record.pid);
+        if (state === "live")
+            throw new PersonalGlossaryRefreshCommitBusyError("another refresh is reclaiming an orphaned personal glossary refresh lock");
+        if (state === "indeterminate")
+            unsafeLock(claimPath, "reclaim claim owner liveness is indeterminate");
+        if (!unlinkOwned(claimPath, claim.descriptor))
+            unsafeLock(claimPath, "reclaim claim changed identity before recovery");
+    }
+    finally {
+        fs.closeSync(claim.descriptor);
+    }
+}
+function reclaimDeadOwner(lockPath, current, prepared, record) {
+    const claimPath = `${lockPath}.reclaim`;
+    const claim = prepareRecord(path.dirname(lockPath), path.basename(claimPath), record);
+    if (!publishPrepared(claim, claimPath)) {
+        fs.rmSync(claim.path, { force: true });
+        fs.closeSync(claim.descriptor);
+        throw new PersonalGlossaryRefreshCommitBusyError("another refresh is reclaiming an orphaned personal glossary refresh lock");
+    }
+    let adopted = false;
+    try {
+        const observed = readRecord(current.descriptor);
+        if (!pathMatches(lockPath, current.descriptor) || !observed || !sameRecord(observed, current.record)) {
+            unsafeLock(lockPath, "owner changed identity before orphan recovery");
+        }
+        const state = ownerState(current.record.pid);
+        if (state === "live")
+            throw new PersonalGlossaryRefreshCommitBusyError();
+        if (state === "indeterminate")
+            unsafeLock(lockPath, "owner liveness is indeterminate");
+        if (!unlinkOwned(lockPath, current.descriptor))
+            unsafeLock(lockPath, "owner changed identity during orphan recovery");
+        if (!publishPrepared(prepared, lockPath))
+            unsafeLock(lockPath, "a successor appeared during orphan recovery");
+        if (!unlinkOwned(claimPath, claim.descriptor)) {
+            unlinkOwned(lockPath, prepared.descriptor);
+            unsafeLock(claimPath, "reclaim claim changed identity before release");
+        }
+        adopted = true;
+        return { descriptor: prepared.descriptor, path: lockPath, record };
+    }
+    finally {
+        if (!adopted)
+            unlinkOwned(claimPath, claim.descriptor);
+        fs.closeSync(claim.descriptor);
+    }
+}
+/** Exclude another consented refresh until evidence and its projection are committed together. */
+export function acquirePersonalGlossaryRefreshCommitLock(options = {}) {
+    const directory = path.dirname(personalGlossaryCandidateProjectionPath(options));
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    fs.chmodSync(directory, 0o700);
+    const lockPath = path.join(directory, ".refresh.lock");
+    removeDeadClaim(`${lockPath}.reclaim`);
+    const record = {
+        schema_version: LOCK_SCHEMA_VERSION,
+        pid: process.pid,
+        token: randomUUID(),
+        created_at: new Date().toISOString(),
+    };
+    const prepared = prepareRecord(directory, path.basename(lockPath), record);
+    try {
+        if (publishPrepared(prepared, lockPath))
+            return { descriptor: prepared.descriptor, path: lockPath, record };
+        const current = openOwnedRecord(lockPath, "owner");
+        if (!current)
+            unsafeLock(lockPath, "owner disappeared during inspection");
+        try {
+            const state = ownerState(current.record.pid);
+            if (state === "live")
+                throw new PersonalGlossaryRefreshCommitBusyError();
+            if (state === "indeterminate")
+                unsafeLock(lockPath, "owner liveness is indeterminate");
+            return reclaimDeadOwner(lockPath, current, prepared, record);
+        }
+        finally {
+            fs.closeSync(current.descriptor);
+        }
+    }
+    catch (error) {
+        if (pathMatches(prepared.path, prepared.descriptor))
+            fs.rmSync(prepared.path, { force: true });
+        fs.closeSync(prepared.descriptor);
+        throw error;
+    }
+}
+export function releasePersonalGlossaryRefreshCommitLock(lock) {
+    try {
+        if (pathMatches(lock.path, lock.descriptor)) {
+            const observed = readRecord(lock.descriptor);
+            if (observed && sameRecord(observed, lock.record))
+                unlinkOwned(lock.path, lock.descriptor);
+        }
+    }
+    finally {
+        fs.closeSync(lock.descriptor);
+    }
+}
+function familySummary(keys, candidateCount, abstentions) {
+    const counts = Object.fromEntries(keys.map((key) => [key, 0]));
+    for (const abstention of abstentions) {
+        if (!(abstention.reason in counts))
+            throw new TypeError("mining produced an unknown abstention reason");
+        counts[abstention.reason] += 1;
+    }
+    return {
+        candidate_count: candidateCount,
+        abstention_count: abstentions.length,
+        abstentions_by_reason: counts,
+    };
+}
+/** Mine and publish the projection bound to the current successfully published evidence generation. */
+export function produceCurrentPersonalGlossaryProjection(options) {
+    const before = readCurrentGeneration(options.tiersDir);
+    if (!before)
+        throw new TypeError("current evidence generation is unavailable");
+    const explicit = mineExplicitGlossaryCandidates({ tiersDir: options.tiersDir });
+    const recurring = mineRecurringGlossaryCandidates({ tiersDir: options.tiersDir });
+    const after = readCurrentGeneration(options.tiersDir);
+    if (!after || explicit.generation !== before.manifest.generation ||
+        recurring.generation !== before.manifest.generation ||
+        after.manifest.generation !== before.manifest.generation) {
+        throw new TypeError("current evidence generation changed during projection production");
+    }
+    const contract = personalGlossaryCandidateProjectionContract();
+    const explicitSummary = familySummary(contract.explicitAbstentionKeys, explicit.candidates.length, explicit.abstentions);
+    const recurringSummary = familySummary(contract.recurringAbstentionKeys, recurring.candidates.length, recurring.abstentions);
+    const miningSummary = {
+        schema_version: "agentera.personalGlossaryMiningSummary.v1",
+        explicit: explicitSummary,
+        recurring: recurringSummary,
+        total_candidate_count: explicitSummary.candidate_count + recurringSummary.candidate_count,
+        total_abstention_count: explicitSummary.abstention_count + recurringSummary.abstention_count,
+    };
+    const projection = projectPersonalGlossaryCandidates({
+        generation: before.manifest.generation,
+        policy_version: PERSONAL_GLOSSARY_MINING_POLICY_VERSION,
+        retained_at: before.manifest.published_at,
+        candidates: [
+            ...explicit.candidates.map((candidate) => ({
+                capsule: candidate.capsule,
+                project_ids: candidate.project_ids,
+            })),
+            ...recurring.candidates.map((candidate) => ({
+                capsule: candidate.capsule,
+                project_ids: candidate.project_ids,
+            })),
+        ],
+        mining_summary: miningSummary,
+    });
+    const persisted = persistPersonalGlossaryCandidateProjectionAfterRefresh(projection, options);
+    const committed = readCurrentGeneration(options.tiersDir);
+    if (!committed || committed.manifest.generation !== projection.generation) {
+        throw new TypeError("current evidence generation changed before projection commit completed");
+    }
+    return {
+        status: persisted.status,
+        generation: projection.generation,
+        policy_version: projection.policy_version,
+        candidate_projection_sha256: projection.projection_sha256,
+        candidate_count: projection.report.mining_summary.total_candidate_count,
+        abstention_count: projection.report.mining_summary.total_abstention_count,
+        path: persisted.path,
+    };
+}